API docs by Redocly

Shift72 Users API (1.0.0)

Download OpenAPI specification:Download

Auth

APIs for authenticating users

Create Auth Session

Creates an auth session on a user's behalf. This can match, create and update the user, similar to the way OAuth signin works.

This is intended for auth integration scenarios where you need to find or create users, then issue them a login.

API Key permissions

Using this API requires a specific limited-permissions key with the users:auth:session permission. Talk to your account manager about getting an API key role set up if you need this API.

Matching users

This API can be used to sign in a specific Shift72 user, or to match them based on an email or external id claim.

Users can be resolved by:

  • providing a specific user_id. This will prevent any other matching.
  • by external id
  • by email (provided you tell us it's trustworthy)

To allow matching by email, you need to have verified the user actually owns the email address to prevent account takeovers.

Creating users

This API can be used to create the user if it doesn't exist. If you pass "create_user": true, and provide an email and name we'll try to create the user if it doesn't exist.

Required parameters:

  • email
  • name

Updating users

If a user is matched, we'll attempt to update their information (name, email, birthdate, gender) if that info is provided.

Fields that may be updated:

  • email, if matched by user_id or external_id and the email is verified.
  • external_id, if the user's existing external id is blank
  • name
  • gender
  • birthdate

Auth session permissions

In future, this API may be changed to only issue unprivileged user sessions — e.g. an admin user authorized this way would be treated as a normal user.

Error codes

  • validation_error: a parameter was not in the required format
  • missing_parameters: not enough info was provided to match a user
  • invalid_parameters: an invalid combination of parameters was provided.
  • user_not_found: a user couldn't be found, and creation was not enabled/possible
  • user_account_suspended: the user's status is not set to active
  • create_user_failed: there was some issue creating the user
  • update_user_failed: there was some issue updating the user details
Authorizations:
ApiKey
Request Body schema: application/json
user_id
number or null

The Shift72 user ID. If provided, this will override any matching by external id or email. If provided, it's invalid to pass create_user: true

external_id
string

An external ID to try and match the user by.

email
string <email>

The user's email address.

email_verified
boolean

Whether you've verified the user actually owns this email. This claim will allow matching by, and updating the user's email address.

create_user
boolean
Default: false

If set to true, create the user if a match isn't found.

number or string

How long should this session last? By default, this will be around 4 hours, but may extend if the token is being actively used.

One of
number

Length of session in seconds, e.g. 14400 for a 4-hour session

name
string

The user's name

birthdate
string or null <date>

The user's birthdate. If provided, this will update their date of birth (used for parental controls and demographic reporting)

gender
string or null
Enum: "male" "female" "other" "diverse"

The user's gender. If provided, the user's profile will be updated to match. This is used for demographic reporting.

Responses

Response Schema: application/json
auth_token
string

An auth token that can be used with the X-Auth-Token header.

object
user_id
number

The Shift72 user's ID

name
string

The user's name

email
string

The user's name

dob
string or null

The user's date of birth (YYYY-MM-DD)

gender
string or null
Enum: "male" "female" "other" "diverse"

The user's gender

bypass_cache
boolean

If true, apps should add the X-Bypass-Cache: 1 header to avoid cached responses. This usually means the user has some level of admin access

permissions
object

The user's permissions. If they're an admin user this will be populated.

Request samples

Content type
application/json
Example

This creates a session for a specific Shift72 user, and will not update any details about their account.

{
  • "user_id": 123456,
  • "expiry": "2025-09-01T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "auth_token": "string",
  • "account": {
    • "user_id": 0,
    • "name": "string",
    • "email": "string",
    • "dob": "string",
    • "gender": "male",
    • "bypass_cache": true,
    • "permissions": { }
    }
}