We support only OAuth 2 over HTTPS.
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.
The OAuth 2 flow depends on the grant type.
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.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.
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.
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.
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.