Configure the OAuth 2.0 API for authentication in FireForm

The following describes OAuth 2.0 in a simplified format to help developers implement the protocol and access APIs developed for use with FireForm. OAuth 2.0 provides an application the ability to issue authenticated requests on behalf of the application itself (as opposed to on behalf of a specific user).

Auth flow

The application-only auth flow follows these steps:

• An application encodes its Client ID and Client Secret into a specially encoded set of credentials.
• An application makes a request to the POST oauth / token endpoint to exchange these credentials for a Bearer Token.
• When accessing the REST API, the application uses the bearer token to authenticate.

Client ID/Secret and developer token

To request a client ID and client secret, submit a FireForm API Access Request. Keep in mind that the client ID and client secret, the bearer token credentials, and the bearer token itself grant access to make requests on behalf of an application. These values should be considered as sensitive as passwords, and must not be shared or distributed to untrusted parties.

Access to FireForm APIs can be deactivated where the client ID and client secret provided to the client are no longer valid. If such a situation occurs, submit a FireForm Support Request.

Issuing application-only requests

The client app authenticates using the Client ID and Secret to receive a bearer token.

1. Encode Client ID and Client Secret: To encode an application's Client ID and Client Secret into a set of credentials to obtain a bearer token:
   1. URL encode the client ID and the client secret according to RFC 1738.
      Note:

      This will not actually change the Client ID and Client Secret; this step should still be performed in case the format of those values changes in the future.
   2. Concatenate the encoded Client ID with a colon (:) and the encoded Client Secret to create a single string, and then Base64-encode the string.
2. Obtain a bearer token: Use the Base64-encoded value calculated in the previous step to obtain a bearer token by issuing a request to POST oauth / token:
   • The request must be a HTTP POST request.
   • The request must include an Authorization header with the value Basic base64_encoded_value (replace base64_encoded_value with value calculated in step 1).
   • The request must include a Content-Type header with the value application/x-www-form-urlencoded;charset=UTF-8.
   • The body of the request must have the line grant_type=client_credentials.

   Example request:

   POST /oauth/token HTTP/1.1
   Host: https://[fireform-tenant-url]
   Authorization Basic
   eHZ5MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw==
   Content-Type: application/x-www-form-urlencoded;charset=UTF-8
   Content-Length: 29
   grant_type=client_credentials

   If the request was formatted correctly, the server will respond with a JSON-encoded payload; for example:

   HTTP/1.1 200 OK
   Status: 200 OK
   Content-Type: application/json; charset=utf-8
   ...
   {"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}

   Applications should verify that the value associated with the token_type key of the returned object is bearer. The value associated with the access_token key is the bearer token.

3. Authenticate API requests with the bearer token: The bearer token may be used to issue requests to API endpoints that support application-only auth. To use the bearer token, construct a normal HTTPS request including an Authorization header with the value of Bearer bearer_token_value (replace bearer_token_value with the bearer token value from step 2). Signing is not required.

   Example request:

   GET /api/v1/patron/search?lastname=smith
   Host: [tenant URL]
   Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAAAAAAAAAA%3DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Common error cases

Following are some common mistakes involved in the negotiation and use of bearer tokens. Not all possible error responses are covered here. Be observant of unhandled error codes and responses.

• Invalid requests to obtain bearer tokens: Attempts to obtain a bearer token with an invalid request (for example, leaving out grant_type=client_credentials), or with incorrect or expired app credentials, will result in an error similar to the following:

  HTTP/1.1 403 Forbidden
  Content-Length: 105
  Content-Type: application/json; charset=utf-8
  ...
  
  {error = "invalid_client","error_description"= "Unable to verify your credentials"}

• API request contains invalid bearer token: Using an incorrect bearer token to make API requests will result in an error similar to the following:

  HTTP/1.1 401 Unauthorized
  Content-Type: application/json; charset=utf-8
  Content-Length: 61
  ...
  
  {error = "invalid_token","error_description"= "Invalid Access Token"}

OAUTH response errors

Error responses are returned with an HTTP 200 or 400 status code (unless specified otherwise), with error and error_description parameters. The error parameter will always be one of the values listed below:

• invalid_request: Request missing a parameter, request includes an unsupported parameter or request repeats a parameter.
• invalid_client: Request contains an invalid client ID or secret.
• invalid_token: Request contains an invalid token.
• unsupported_grant_type: Request contains an invalid code.

Get help