Please review this guide to become familiar with our supported authentication methods to use our API resources. You should understand the differences between each authentication type before you start your development or integration.

NOTE: at this time all authentication methods provide administrator level authorization. Access cannot be restricted or scoped to specific resources or actions.

Access Tokens

❗️
All partners using 7shifts API resources should use OAuth Clients for authentication. Access Tokens are intended for personal usage.

Access tokens can be used to access our API resources. They give you admin level access, are long lived, and are simple to implement.

If you are using 7shifts API resources for internal usage and are not looking to be a technology partner of 7shifts, you should use access tokens for authentication.

Creating Access Tokens

Generate an Access Token by navigating to "Company Settings", then "Developer Tools". Under the Access Token Section click "Create Access Token".

Give your access token a descriptive name, examples are Production POS or Zapier integration.

The technical contact must be an active company admin, who has logged in at least once. It is recommended that you assign an admin who knows about the use of the token. 7shifts may reach out to the technical contact in case of important notices regarding the use of the tokens or API resources.

When you create an access token, by default it is assigned the latest API version. If the x-api-version header is not included in the API request it will default to the API version assigned to the token. The default version can be updated via the Edit Access Token process.

NOTE If the account assigned to the token technical contact is deactivated or has their admin status removed, the access token will become invalid and fail to authenticate properly. You can edit an access token and assign a valid admin as the technical contact to make the access token valid again.

Using Access Tokens

To use your token, use the bearer authentication scheme. Send the token in the Authorization header when making requests as per the example below.

curl --request GET --url 'https://api.7shifts.com/v2/companies'  
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Editing Access Tokens

You can edit an access token and change the name, technical contact and base API version.

To edit an access token, click the side menu item on the right of the access token, then click delete. Changing the name or the technical contact will not impact the use of the access token and can be done safely.

You are also able to change the base API version assigned to the token, from a list of supported versions. If the x-api-version header is not included in the API request it will default to the API version assigned to the token. It is recommended that you only change the version if you don't use the x-api-version header on API requests and wish to change the API version used on all of your requests.

Deleting Access Tokens

When you no longer need to use an access token it is recommended that you delete it. This will increase the security of your data by removing access to tokens that could be leaked or shared without your knowledge.

To delete an access token, click the side menu item on the right of the access token, then click delete. Type DELETE to confirm. Once you click delete, the access token is deleted and this action cannot be undone. This will prevent any application using it from authenticating successfully to our API resources.

OAuth Clients

OAuth Client authentication requires a bearer token before making API requests. To create a token, you'll need to specify a scope, the client ID, and the client secret. Once a token is created, you'll be able to use the bearer tokens for 1 hour before they expire. It is recommended that you only request the scopes you intend to use.

Below is an example of requesting a token

curl --request POST --url 'https://app.7shifts.com/oauth2/token' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id={CLIENT_ID}' 
--data-urlencode 'client_secret={CLIENT_SECRET}' 
--data-urlencode 'scope=v1_access {ADDITIONAL_SCOPES}'

An example token response

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

To use the token, use the bearer authentication scheme. Send the token in the Authorization header when making requests as per the example below.

url --request GET --url 'https://api.7shifts.com/v2/companies' \
--header 'x-company-guid: GUID' \
--header 'Authorization: Bearer {ISSUED_TOKEN}'

For more information on OAuth Clients refer to our OAuth Authentication guide.