App Authorization Schemes Help

What authorization schemes do you support?

We support only OAuth 2 over HTTPS.

What OAuth 2 authorization grant types do you support?

We support the following grant types:

We are ware of the Implicit grant and the Resource Owner Password Credentials grant, as per the OAuth 2 spec, but we do not support those grant types.

How does the OAuth 2 flow work?

The OAuth 2 flow depends on the grant type.

Authorization Code Grant
  • You ask the user to approve limited access to their user account by your app.
  • Your server sends a background request to our server to request an access token.
  • Our server responds with an access token.
Client Credentials Grant
  • Your server sends a background request to our server to request an access token.
  • Our server responds with an access token.
Refresh Token Grant
  • Your server sends a background request to our server to request an access token.
  • Our server responds with an access token.

How do I use the Authorization Code grant?

Step One

Redirect the user to the authorization server at https://www.alertersystem.com/oauth/v2/authorize/ with the following parameters in the query string:

  • response_type with the value code.
  • client_id with your app's App ID.
  • redirect_uri with your app's Callback URL. This parameter must be exactly the same as one of the Callback URL entries registered for your app.
  • scope with a space delimited list of Scopes. The scope(s) must correspond with the scope(s) registered for your app. It could be a subset of the registered scopes to limit the access of a specific user.
  • state with any string of your choice. This parameter is optional but highly recommended. We don't use the value, we just send it back to you (see below) for verification purposes. You should store the string in the user’s session to be validated when they return.

The user will be asked to login to their AlerterSystem.com user account and approve the access that's requested by your app.

If the user approves the access request, they will be redirected to the Callback URL that was sent in the redirect_uri parameter above. The user will arrive at the Callback URL with the following parameters in the query string:

  • code with the authorization code.
  • state with the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by your app rather than another app.

If the user denies the access request, they will be redirected to the Callback URL that was sent in the redirect_uri parameter above. The user will arrive at the Callback URL with the following parameters in the query string:

  • state with the state parameter sent in the original request.
  • error with the value access_denied.
  • error_description with the reason that the access was denied.
Step Two

If the user approved the request, your app must now send a background POST request to the access token server at https://www.alertersystem.com/oauth/v2/access-token/ with the following parameters:

  • grant_type with the value of authorization_code.
  • client_id with your app's App ID.
  • client_secret with your app's App Secret.
  • redirect_uri with the same Callback URL that was sent in Step One above.
  • code with the authorization code that was received in the code parameter of the query string above.

Our access token server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer.
  • expires_in with an integer representing the lifetime of the access token in seconds.
  • access_token with a JSON Web Token (JWT) signed with the access token server’s private key. This is the access token that must be sent in the request headers of all API requests to authenticate the user.
  • refresh_token with an encrypted payload that can be used to refresh the access token when it expires.

Store the values of access_token, refresh_token, and the access token expiry date in your database.

Upon expiry of an access token obtained with the Authorization Code grant, you can use the Request Token grant to request a new access token in the background, without requiring any action by your user.

API requests that are authenticated using an access token obtained with the Authorization Code grant always access the resources in the user account that approved the authentication request in Step One above.

How do I use the Client Credentials grant?

Send a background POST request to the access token server at https://www.alertersystem.com/oauth/v2/access-token/ with the following parameters:

  • grant_type with the value of client_credentials.
  • client_id with your app's App ID.
  • client_secret with your app's App Secret.
  • scope with a space delimited list of Scopes. The scope(s) must correspond with the scope(s) registered for your app. It could be a subset of the registered scopes.

Our access token server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer.
  • expires_in with an integer representing the lifetime of the access token in seconds.
  • access_token with a JSON Web Token (JWT) signed with the access token server’s private key. This is the access token that must be sent in the request headers of all API requests to authenticate the request.

Store the value of access_token and the access token expiry date in your database.

Upon expiry of an access token obtained with the Client Credentials grant, you must request a new access token by redoing the Client Credentials grant process.

API requests that are authenticated using an access token obtained with the Client Credentials grant always access the resources in the user account that owns the application, i.e., your own user account. It cannot be used to access resources in other user accounts.

If your app needs to access resources in other user accounts, then you must use the Authorization Code grant.

How do I use the Refresh Token grant?

Send a background POST request to the access token server at https://www.alertersystem.com/oauth/v2/access-token/ with the following parameters:

  • grant_type with the value of refresh_token.
  • refresh_token with value of the refresh token.
  • client_id with your app's App ID.
  • client_secret with your app's App Secret.
  • scope with a space delimited list of Scopes. The scope(s) must correspond with the scope(s) registered for your app. This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes.

Our access token server will respond with a JSON object containing the following properties:

  • token_type with the value Bearer.
  • expires_in with an integer representing the lifetime of the access token in seconds.
  • access_token with a JSON Web Token (JWT) signed with the access token server’s private key. This is the access token that must be sent in the request headers of all API requests to authenticate the user.
  • refresh_token with an encrypted payload that can be used to refresh the access token when it expires.

Store the values of access_token, refresh_token, and the access token expiry date in your database.

Upon expiry of an access token obtained with the Refresh Token grant, you can again use the Request Token grant to request a new access token in the background, without requiring any action by your user.

API requests that are authenticated using an access token obtained with the Refresh Token grant always access the resources in the user account that approved the original authentication request in the Authentication Code grant process above.

Only access tokens obtained using the Authorization Code grant can be refreshed with the Refresh Token grant.

What error responses can be expected from the authorization process?

If the server denies an authorization or access token request, it will return a JSON response construct with one of the following error codes in the error entry:

  • invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the app, or is otherwise malformed.
  • invalid_client: App authentication failed (e.g., unknown app, no app authentication included, or unsupported authentication method).
  • invalid_grant: The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another app.
  • unauthorized_client: The authenticated app is not authorized to use this authorization grant type.
  • unsupported_grant_type: The authorization grant type is not supported by the authorization server.
  • invalid_scope: The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

Cannot find the answer to your question? Visit our support page for personalized support by our staff.