Toast User Management API Guide

Auth method: OAuth 2.0 (client credentials grant)

Setup steps

1. Register as a Toast API partner or integration developer via the Toast Partner Portal.
2. Obtain a client_id and client_secret from the Toast developer dashboard.
3. POST to https://ws-api.toasttab.com/authentication/v1/authentication/login with client_id and client_secret to receive a Bearer token.
4. Include the Bearer token in the Authorization header for all subsequent API requests.
5. Tokens expire; re-authenticate using the same client credentials flow when a 401 is returned.

Required scopes

List employees

• Method: GET
• URL: https://ws-api.toasttab.com/labor/v1/employees
• Watch out for: The Toast-Restaurant-External-ID header is mandatory; omitting it returns a 400 error.

Request example

GET /labor/v1/employees?pageToken=&pageSize=100
Authorization: Bearer {token}
Toast-Restaurant-External-ID: {restaurantGuid}

Response example

{
  "employees": [
    {"guid":"abc-123","firstName":"Jane","lastName":"Doe","email":"jane@example.com"}
  ],
  "pageToken": "next-page-token"
}

Get employee by GUID

• Method: GET
• URL: https://ws-api.toasttab.com/labor/v1/employees/{employeeGuid}
• Watch out for: Returns 404 if the employee GUID does not belong to the restaurant specified in the header.

Request example

GET /labor/v1/employees/abc-123
Authorization: Bearer {token}
Toast-Restaurant-External-ID: {restaurantGuid}

Response example

{
  "guid": "abc-123",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "deleted": false
}

Create employee

• Method: POST
• URL: https://ws-api.toasttab.com/labor/v1/employees
• Watch out for: Creating an employee does not automatically grant POS access; job assignments and passcode must be set separately.

Request example

POST /labor/v1/employees
Authorization: Bearer {token}
Toast-Restaurant-External-ID: {restaurantGuid}

{"firstName":"John","lastName":"Smith","email":"john@example.com"}

Response example

{
  "guid": "def-456",
  "firstName": "John",
  "lastName": "Smith",
  "email": "john@example.com",
  "deleted": false
}

Update employee

• Method: PATCH
• URL: https://ws-api.toasttab.com/labor/v1/employees/{employeeGuid}
• Watch out for: Only fields included in the PATCH body are updated; omitted fields retain their current values.

Request example

PATCH /labor/v1/employees/def-456
Authorization: Bearer {token}
Toast-Restaurant-External-ID: {restaurantGuid}

{"email":"john.new@example.com"}

Response example

{
  "guid": "def-456",
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.new@example.com"
}

Authenticate (get token)

• Method: POST
• URL: https://ws-api.toasttab.com/authentication/v1/authentication/login
• Watch out for: userAccessType must be TOAST_MACHINE_CLIENT for server-to-server integrations. Token expiry is 1 hour.

Request example

POST /authentication/v1/authentication/login
Content-Type: application/json

{"clientId":"your-client-id","clientSecret":"your-client-secret","userAccessType":"TOAST_MACHINE_CLIENT"}

Response example

{
  "token": {
    "tokenType": "Bearer",
    "token": "eyJ...",
    "expiresIn": 3600
  }
}

List jobs

• Method: GET
• URL: https://ws-api.toasttab.com/labor/v1/jobs
• Watch out for: Job GUIDs are required when assigning jobReferences to an employee; jobs are restaurant-scoped.

Request example

GET /labor/v1/jobs
Authorization: Bearer {token}
Toast-Restaurant-External-ID: {restaurantGuid}

Response example

{
  "jobs": [
    {"guid":"job-111","title":"Server","deleted":false}
  ]
}

• Rate limits: Toast does not publicly document specific numeric rate limits in its developer docs. Rate limiting is enforced but thresholds are not published.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No explicit rate limit values, headers, or Retry-After behavior documented in official Toast developer docs as of research date.

• Pagination method: token

• Default page size: 100

• Max page size: 100

• Pagination pointer: pageToken

• Webhooks available: No

• Webhook notes: Toast does not publicly document a webhook system for employee/user-management events in its developer docs. Event-driven notifications for employee changes are not described in official documentation.

• Alternative event strategy: Poll GET /labor/v1/employees with a modifiedDate filter or pageToken-based pagination to detect changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Toast does not offer a native SCIM 2.0 endpoint according to official documentation.
• No IdP (Okta, Entra, Google Workspace, OneLogin) SCIM connector is officially documented by Toast.
• Employee provisioning must be performed via the Toast Labor API directly.

For provisioning a new hire across multiple locations, authenticate once, retrieve your restaurant GUID list, then POST /labor/v1/employees per location with firstName, lastName, email, and jobReferences.

Store the returned employee GUID per location - there is no shared identity across locations, so your identity graph must maintain a per-location GUID map for each employee.

For deprovisioning, PATCH /labor/v1/employees/{employeeGuid} with {"deleted": true for each location the employee belongs to.

Toast uses soft deletes only;

records persist and are retrievable with includeDeleted=true.

There is no hard-delete endpoint, and the deleted field is the sole mechanism for access revocation via API.

For HR roster sync, paginate GET /labor/v1/employees?pageSize=100 per location using pageToken until exhausted, then diff against your HR system using externalId as the correlation key.

There is no delta or changelog endpoint - full pagination is required on every sync cycle.

Use modifiedDate on the employee object to minimize unnecessary PATCH calls.

Provision a new employee across multiple restaurant locations

1. Authenticate via POST /authentication/v1/authentication/login to obtain a Bearer token.
2. Retrieve the list of restaurant GUIDs for the organization (via the Toast Configuration API or stored mapping).
3. For each restaurant GUID, POST /labor/v1/employees with the employee's firstName, lastName, email, and desired jobReferences.
4. Store the returned employee GUID per restaurant for future updates or deprovisioning.

Watch out for: Employee records are not shared across restaurant locations; a separate POST is required per location. There is no org-wide employee create endpoint.

Deprovision (soft-delete) a departing employee

1. Authenticate to obtain a Bearer token.
2. For each restaurant location the employee belongs to, PATCH /labor/v1/employees/{employeeGuid} with {"deleted": true} and the appropriate Toast-Restaurant-External-ID header.
3. Verify the employee no longer appears in GET /labor/v1/employees (without includeDeleted=true).

Watch out for: Toast uses soft deletes; the employee record persists and is retrievable with includeDeleted=true. There is no hard-delete endpoint documented.

Sync employee roster from an external HR system

1. Authenticate and retrieve all employees via GET /labor/v1/employees?pageSize=100 for each restaurant location, paginating with pageToken until exhausted.
2. Compare the retrieved roster against the HR system's employee list using externalId as the correlation key.
3. For new HR employees not in Toast, POST /labor/v1/employees to create them.
4. For changed employees (name, email, job), PATCH /labor/v1/employees/{guid} with updated fields.
5. For terminated employees present in Toast but not in HR, PATCH with {"deleted": true}.

Watch out for: There is no delta/changelog endpoint; full pagination is required on each sync cycle. Store modifiedDate to minimize unnecessary updates.

The location-scoped API model is the primary architectural trap: building an integration without accounting for per-location GUID iteration will silently miss employees at locations not explicitly enumerated. This is especially dangerous for offboarding - a departing employee soft-deleted at one location retains active records at all others unless each is patched individually.

Webhooks are not documented for employee events. All change detection must be polling-based, which means your sync frequency directly determines how stale your identity graph can become between cycles. Pair this with undocumented rate limits (implement exponential backoff on 429s;

no Retry-After header is documented) and full roster pagination at scale requires careful throttle management.

Two additional caveats worth flagging explicitly: the passcode field is write-only and never returned in GET responses, so your system cannot audit or verify POS passcode state after creation.

And creating an employee record via POST does not automatically grant POS terminal access - job assignments and passcode must be set in the same or a subsequent request, or the employee cannot clock in.