OAuth Authorization Documentation

Alterdesk OAuth Authorization

Authorization for this API is going through our OAuth v2 server located at https://im.alterdesk.com.

Step 1. User Authorization

Register your application as a Company Admin in the Company Settings Advanced tab located here. In your application direct the user https://im.alterdesk.com/oauth/authorize with the following GET parameters:

response_type	Whether the endpoint returns an authorization code. For all applications, a value of `code` should be used.
client_id	Client ID from where you registered your application.
redirect_uri	An URI where the response will be redirected. Filled in when you registered your application.
scope	Scopes you want authorization for: `read write admin`
state	A unique string to be passed back to the redirect URI on completion of this request. This should be used to avoid forgery attacks by passing in a value unique to the user you are authenticating and checking when the authentication completes.

Step 2. Access Token Issuing

After the user accepted the authorization, Alterdesk will use the redirect URI to redirect back to your site with GET parameters code and state. If the state does not match the request has been created by a third party and the authorization process should be aborted.

To exchange the authorization code for an access token use the https://im.alterdesk.com/oauth/token with the following POST parameters:

client_id	Client ID from where you registered your application.
client_secret	Client Secret from where you registered your application.
code	The code from the previous step.
grant_type	The type of authorization being executed, should be `authorization_code`.
redirect_uri	An URI which must match the originally submitted URI. Filled in when you registered your application.

The request must have a Content-Type of application/x-www-form-urlencoded. See this example post body:

client_id=registered-client-id&client_secret=super-secret-client-secret&code=generated-code&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fapi.alterdesk.com%2Fdocs%2Fcallback

The access token will be present in the JSON response and can be used to call protected API methods on behalf of the user:

{
    "access_token": "generated-access-token",
    "token_type": "bearer",
    "refresh_token": "generated-refresh-token",
    "expires_in": "expiration-int-seconds",
    "scope": "read write"
}

Request Signing

To sign the API request use the access_token from the last step and add it to the Authorization header.

Authorization: Bearer generated-access-token

It is also possible to use the access_token URL parameter.

/v1/me?access_token=generated-access-token

Refresh Token

Issued access tokens can have an expiration (in seconds) and attached refresh token. It is up to the implementing application to use the refresh token to request a new access token when it is expired. In case the refresh token has expired the user needs to be authenticated again.

To exchange the refresh token for a new access token use the https://im.alterdesk.com/oauth/token with the following POST parameters:

client_id	Client ID from where you registered your application.
client_secret	Client Secret from where you registered your application.
refresh_token	The refresh token from the previous step.
grant_type	The type of authorization being executed, should be `refresh_token`.

The request must have a Content-Type of application/x-www-form-urlencoded. See this example post body:

client_id=registered-client-id&client_secret=super-secret-client-secret&refresh_token=stored-refresh-token&grant_type=refresh_token

The new access token will be present in the JSON response and can be used to call protected API methods on behalf of the user:

{
    "access_token": "generated-access-token",
    "token_type": "bearer",
    "refresh_token": "generated-refresh-token",
    "expires_in": "expiration-int-seconds",
    "scope": "read write"
}

Access Token Generation Form

To generate access tokens without implementing the OAuth steps explained above the following form can be used in combination with your Client ID and Secret. This method will add the api host to your redirect URIs.

Client ID
Client Secret
Scopes	read write admin frame gateway api.provision video chat

Generated token: