Authenticating API requests
LTIAAS API endpoints must only be called from your application's back-end. Authenticated API requests will include your API key, so making them from the front-end might result in your credentials getting leaked.
Ltik based authentication
During an LTI® launch, LTIAAS will perform the LTI® protocol authentication flow and then redirect the user to your application, this redirection will also append a query parameter called ltik to your account's registered target launch URL:
This token represents a single LTI® launch and allows LTIAAS to store and retrieve information specific to that launch context.
You can then combine your account's API Key and the ltik token received to build the following authorization header:
Authorization: LTIK-AUTH-V2 <API_KEY>:<LTIK>
Example:
Authorization: LTIK-AUTH-V2 df06d55e-3b0f-4121-b60f-c39469b5b550:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0
The ltik token represents a single LTI® launch, therefore each token must only be used in requests made within the same launch context in which it was generated. Using an ltik token outside of its originating context can cause unexpected behavior and provide outdated information.
Due to the nature of LTI®, the ID Token related to a launch should not be trusted after some time, for this reason each ltik token expires after 24 hours.
The ltik based authentication schema is accepted by all of the LTIAAS service API endpoints.
Service key based authentication
If you need to make API requests outside of the context of an LTI® launch, you can use the service key based authentication schema.
Due to the nature of LTI®, it's recommended to always utilize the services synchoronously, within the context of an LTI® launch. For most use cases it should be enough and a lot easier to trigger periodic tasks when someone launches to your tool.
After receiving an LTI® launch you can use the ltik based authentication to retrieve an ID Token. If the current LTI® launch context has access to at least one of the Assignment and Grades or Names and Roles Provisioning LTI® services, the ID Token you retrieved will have an idtoken.services.serviceKey field.
// Building Ltik based API authentication header
const authorizationHeader = `LTIK-AUTH-V2 ${API_KEY}:${LTIK}`
const headers = { Authorization: authorizationHeader }
// Making /api/idtoken GET request
const response = requests.get('https://your.ltiaas.com/api/idtoken', { headers })
// Retrieving service key
const serviceKey = response['services']['serviceKey']
You can then combine your account's API Key with the serviceKey retrieved to build the following authorization header.
Authorization: SERVICE-AUTH-V1 <API_KEY>:<SERVICE_KEY>
Example:
Authorization: SERVICE-AUTH-V1 df06d55e-3b0f-4121-b60f-c39469b5b550:eyJhbGcieyJzdWIiOiIxMjM0.OiJIUzI1NiIsInR5cCI6IkpXVCJ9
Unlike the ltik token, the serviceKey will not expire after 24 hours and can be used outside of an LTI® launch. This allows you to, for example, run a cron job to synchronize grades once a day.
It's important to note that each serviceKey represents a single LTI® launch context, which usually translates to an activity in the LMS. So you need to be mindful of that when storing and using these tokens. Calling the API using a certain serviceKey will yield results from the launch context that it's associated with.
You can learn more about using the service key based API authentication method in the Accessing the API asynchronously guide.
Bearer API key based authentication
A select few API endpoints are not related to an LTI launch context, such as during dynamic registration. Therefore, an LTIK or service key is not available. Only the API key needs to be sent in the form of a Bearer token.
Authorization: Bearer <API_KEY>
Example:
Authorization: Bearer df06d55e-3b0f-4121-b60f-c39469b5b550
