Authentication

How to request and use Access Tokens.

1. Get your ClientID and Secret

If you are an Institution: make sure that you have generated your ClientID and Secret for institutional use on the Identity Service page.

If you are a Partner of Instructure: make sure that you have received your ClientID and Secret from your Institution.

Keep your ClientID and Secret in a safe place! Do not share with anyone else!

2. Requesting the Access Token

Using the ClientID and Secret you are ready to request for an access token. The access token is a JSON Web Token, that grants access to the targeted Instructure service. This is a short lived token, it needs to be renewed periodically. Typically expires in one hour.

The following code snippet uses curl to send the request and jq to extract the access token from the answer:

ACCESS_TOKEN=$(curl --request POST https://api-gateway.instructure.com/ids/auth/login \
--user "${CLIENT_ID}:${SECRET}"  \
--data-urlencode 'grant_type=client_credentials' | jq -r '.access_token')

echo $ACCESS_TOKEN

3. Using the Access Token

Once you received the access token you can call the desired service. The example below will demonstrate this by querying the list of table names that exist in Canvas using the CD2 service. The access token shall be passed as a bearer token in the Authorization header:

curl --request GET 'https://api-gateway.instructure.com/dap/query/canvas/table' \
--header "Authorization: Bearer ${ACCESS_TOKEN}" 

Upon success the call returns with a list of table names available Canvas.

Deprecation Notice for x-instauth Header Parameter

The use of x-instauth header parameter to pass the access token is considered deprecated. Instead use the Authorization header parameter as shown above. In case both header parameters are filled (x-instauth and Authorization), Authorization will take precedence.

Due to compatibility reasons x-instauth will be still supported for a while, but all clients are encouraged to switch to the new header value as soon as possible.