Authenticating with the API

The StudyTeam APIs use the OAuth 2.0 Client Credentials Flow for authentication. The caller must first submit a request to retrieve a JSON Web Token (JWT), which will then be used on all subsequent API calls.

The Client Credentials grant is commonly used in machine to machine authentication scenarios where the caller is not a user in the traditional sense (eg: someone logging in to a website), but is an automated system. The request looks similar to a traditional Basic Authentication flow where you will be provided with a Client ID and a Client Secret. It is imperative that these remain secure and only configured on the back-end application making the requests. Anyone with these can authenticate as you.

Most programming languages have a library that can handle the authentication flow for you, but it is helpful to understand what is going on under the covers. The basic request/response flow looks like this:

First, send a request to retrieve the token. The request body should contain a JSON payload with four fields:

Client ID: like a username, but for a machine user. Will be provided to you.
Client Secret: like a password, but for a machine user. Will be provided to you.
Audience: the audience is an identifier designating the requested API. Will be provided to you
Grant Type: the grant type, which in our case is "client_credentials"

Note: The Client ID and Client Secret are specific to the environment with which you are integrating. For this reason, you will be provided a separate set of client credentials for each environment (i.e. Staging and Production).

POST /oauth/token
content-type: application/json

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "audience": "AUDIENCE",
  "grant_type": "client_credentials"
 }

The response, if successful, will be a JSON payload containing the access token you will use on subsequent API calls as well as the type of token ("Bearer") and the number of seconds until the token will expire (eg: 3600 seconds or 60 minutes). Your application should cache the token and continue using it until it is about to expire.

{
  "access_token": "ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Next, the token will be set as the "authorization" header and used to interact with the API. The header has the format: authorization: Bearer [your token here]

POST /api/something
content-type: application/json
authorization: Bearer ACCESS_TOKEN

Body of the request

Finally, your application should be able to handle the token expiration. After 60 minutes the token will expire and the authentication endpoint will need to be queried again for a new token. When authentication fails, the server will return a 401 HTTP status response. If this is received, the application should query the authentication endpoint again to receive a new token for subsequent requests.

See the Authentication API Docs for more information