API Authentication

Wristband uses the following two schemes to authenticate API requests:

1. Bearer Authentication
2. Basic Authentication

Most Wristband APIs use Bearer authentication. However, for APIs that must be accessed before a bearer token is created, Basic authentication is required instead. In the sections below, we'll explain how to authenticate with Wristband APIs using these two schemes.

Bearer Authentication

This is the primary method for authenticating API requests. To authenticate using the Bearer authentication scheme, you'll first need to acquire an access token. Access tokens can be acquired for the following two entities:

1. Users
2. Clients

Acquiring Access Tokens For Users

User access tokens are generated by calling the Create Tokens API using the authorization_code grant type. Typically, you'll call the Create Tokens API as part of your Callback Endpoint, after a user successfully logs in to your application.

Acquiring Access Tokens For Clients

Client access tokens are generated by calling the Create Tokens API using the client_credentials grant type. This is the recommended way to acquire an access token when manually calling Wristband APIs with tools like cURL or Postman. For more information on how to create access tokens using the client_credentials grant type, please see the Getting Access Tokens to Test Wristband APIs tutorial.

Using Access Tokens to Authenticate

Once you've acquired an access token (for either a user or client), you can then pass it in the HTTP Authorization header using the Bearer authentication scheme as shown below:

Authorization: Bearer <access_token>

When the request is received, Wristband validates the access token to authenticate the user or client. If the access token is valid, Wristband processes the API request; otherwise, a 401 response is returned.

Identifying APIs That Use Bearer Authentication

In the API reference, to identify which APIs require Bearer authentication, check the "Credentials" section to see if it says "Bearer".

Basic Authentication

Some Wristband APIs must be called before a bearer token can be created. These APIs use Basic authentication, which requires credentials to be computed by base64 encoding a client ID and secret, separated by a colon (:). For example, if the client ID was client1 and its corresponding secret was abc, the credentials would be computed as follows:

base64Encode(client1:abc)

Once the credentials have been computed, you can then pass them in the HTTP Authorization header using the Basic authentication scheme as shown below:

Authorization: Basic <credentials>

When the request is received, Wristband validates the credentials to authenticate the client. If the credentials are valid, Wristband processes the API request; otherwise, a 401 response is returned.

Identifying APIs That Use Basic Authentication

In the API reference, to identify which APIs require Basic authentication, check the "Credentials" section to see if it says "Basic".

Unauthenticated APIs

Some APIs, like the Authorize API, don't require authentication. These APIs are either intended for public access or use an ephemeral code to authorize the request. For these APIs, the HTTP Authorization header can be omitted from the request.

Identifying Unauthenticated APIs

In the API reference, to identify which APIs don't require authentication, check to see if the "Credentials" section is missing.