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",
"scope": "read write",
"token_type": "bearer"
}

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

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