OAuth Authentication

This guide covers the OAuth 2.0 client credentials flow used by 7shifts partner integrations.

How OAuth differs from access tokens

If you've used access tokens before, three things change:

1. Tokens are short-lived. OAuth bearer tokens expire after 1 hour. Access tokens don't expire.
2. Every request needs an x-company-guid header. See Understanding the company GUID below.
3. Each customer must explicitly grant your app access before you can call the API on their behalf.

Prerequisites

You need an OAuth client, which is issued during partner onboarding. To create one, 7shifts needs:

• A technical email contact — a valid address not tied to an individual user account
• First and last name of the primary technical contact
• Your official company name, shown to customers during authorization
• A PNG of your company logo, shown to customers during authorization
• A callback URL, used to receive the company GUID after a grant is approved

You'll receive a client ID and client secret. Store the secret securely as it cannot be recovered. Resetting a client requires re-authorizing every customer you've already integrated with.

Understanding the company GUID

This is the most challenging concept of this auth flow, please review carefuly.

Your OAuth token is issued to your client, not to a customer. On its own, a token doesn't identify whose data you're asking for and it could be used for any company that has granted your client access.

The company GUID is that link. It's created when a specific customer grants your OAuth client access to their account, and it maps 1:1 to a company.

You send it on every request:

x-company-guid: {GUID}

This matters because some endpoints don't take a company_id in the path or query string. For those, the GUID is the only thing scoping the request to the right company's data.

Access tokens never use this header. An access token is already bound to a single company.

The OAuth flow

The client credentials flow lets your application authenticate directly with the 7shifts API with minimal user interaction, requiring only an authorization grant.

Step 1: The customer grants your client access

Before you can access a customer's data, a company administrator on their account must authorize your OAuth client. Send them to:

https://app.7shifts.com/generate_token?client_id={CLIENT_ID}

We recommend surfacing this link on your platform's Integrations or Marketplace page.

To protect against CSRF, or to carry your own identifier through the flow, include a state parameter. It's an arbitrary string returned to your redirect URL when the grant is created:

https://app.7shifts.com/generate_token?client_id={CLIENT_ID}&state={PARTNER_PROVIDED_STRING}

Step 2: What the administrator sees

1. If not already signed in, the admin logs in to 7shifts.

2. If they administer multiple companies, they choose which one to grant access to.

3. They see your company logo and name, and choose to grant access.

4. On approval, a grant GUID is created.

Step 3: Receiving the GUID

Without a redirect URL configured, the customer sees a page displaying the GUID, which they copy and send to you manually. This is the simpler setup for testing, since you don't need a handler yet.

With a redirect URL configured, the customer is redirected to your URL with the GUID and company ID attached:

https://redirect_url?guid={GUID}&company_id={COMPANY_ID}#guid={GUID}&company_id={COMPANY_ID}

If you passed a state parameter, it's appended:

https://redirect_url?guid={GUID}&company_id={COMPANY_ID}&state={PARTNER_PROVIDED_STRING}#guid={GUID}&company_id={COMPANY_ID}

Handle the redirect by confirming completion to the customer, or by sending them to any further configuration you need.

To add a redirect URL to your client, contact 7shifts support.

A company admin can also retrieve the GUID later under Company Settings → Developer Tools → Connected Apps, using the "Copy the GUID to the clipboard" action.

Step 4: Request a token

Request:

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={SCOPES}'

Response:

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

Step 5: Verify

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

A successful response includes an identity_id.

Response:

{
    "data": {
        "identity_id": 123456,
        "users": [
            {
                "id": 555, ...
            }
        ]
    },
    "object": "whoami"
}

Step 6: Make requests

Every request needs both headers:

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

Token expiry

Tokens expire 1 hour after creation. Request a new one using the same call in Step 4. There is currently no refresh token mechanism; one is planned.

Revoking Grants Notifications

A company administrator can disconnect your integration at any time under Company Settings → Developer Tools → Connected Apps.

Subscribe to the authorization.revoked webhook to be notified immediately when a grant is revoked, so you can stop making requests for that company.