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

AuthorizationstringRequired

Responses

200

Successful operation

application/json

The answer received as a result of successful authorization.

access_tokenstring · jsonOptional

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_inintegerOptional

The expiration time of the access_token in seconds.

Example: 3599

scopestringOptional

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 region:REGION_ID

token_typestringOptional

The type of the access token.

Example: bearer

400

The request could not be understood due to malformed syntax

403

Request forbidden due to missing/invalid authentication information

post/ids/auth/login

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 DAP Query API. 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.