Authentication

How to obtain and use the Access Token (JWT)

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.

Issue a JSON Web Token

post

Issues a JSON Web Token (JWT) to be used in subsequent to API calls.

The received JWT (see access_token property in the Responses section) needs to be passed in the header of every upcoming service call as a Bearer token.

Note that this is a short lived token, it needs to be renewed periodically. Typically expires in one hour.

Authorizations

Responses

200

Successful operation

application/json

400

The request could not be understood due to malformed syntax

403

Request forbidden due to missing/invalid authentication information

post

Shell

# CLIENT_ID: Your ClientID. Eg: 'e5cfa033-6966-48c4-b2a2-03731a2cabc4'
# SECRET: The password associated with your ClientID
# Request for access token and extract it 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

{
  "access_token": "text",
  "expires_in": 3599,
  "scope": "SERVICE_ID principal:PRINCIPAL_ID partner:PARTNER_ID\nregion:REGION_ID\n",
  "token_type": "bearer"
}

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.