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.
API Keys
API key authentication is deprecated
As of August 31, 2022 API key authentication is no longer recommended. If your company has already generated an API key, you will continue to have access to it.
If you require a new API key you will be able to create one, although it is only recommended if the integration you are using does not use a supported authentication method.
API key carries many privileges, so be sure to keep them secret! Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.
Example API request using API key authentication.
curl --request GET --url https://api.7shifts.com/v1/companies
--header 'Accept: application/json'
--header 'Authorization: Basic {API_KEY}'
Don't have an API Key?
Generate an API key by first creating a 7shifts account. Once it's created, navigate to "Company Settings", then "Developer Tools". Under the Access Token Section click "Generate".
V1 endpoint access only
API key authentication is only supported by V1 endpoints. If you wish to use V2 endpoints you will need to acquire use Access tokens or an OAuth client.
Access Tokens
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.
All partners using 7shifts API resources should use OAuth Clients 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.