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

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.

POSThttps://api-gateway.instructure.com/ids/auth/login

Authorization

basic

Response

200400403

Successful operation

Body

application/json

access_tokenstring (json)

JSON Web Token, that grants access to the targeted Instructure services. Note that this is a short lived token, it needs to be renewed periodically. Typically expires in one hour.

expires_ininteger

The expiration time of the access_token in seconds.

Example: 3599

scopestring

Specifies the scope, the institute (principal), the partner and the region for which the access_token was issued. These values are separated with a white space in the form of SERVICE_ID principal:PRINCIPAL_ID partner:PARTNER_ID region:REGION_ID.

Example: "SERVICE_ID principal:PRINCIPAL_ID partner:PARTNER_ID\nregion:REGION_ID\n"

token_typestring

The type of the access token.

Example: "bearer"

Request

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

Response

200

{
  "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.