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