Authentication

The Hopshift employee REST API uses API keys for authentication. Requests to /api/v1/employees endpoints must include a valid API key in the Authorization header.

This page describes employee integration keys from Group Settings → API Keys. For personal shift, approval and payroll management, authorize a separate MCP connection and follow the MCP setup guide. OAuth connections and personal mcp:management keys follow their creator's current permissions and do not grant employees:read access to REST endpoints.

Key types

Group Settings → API Keys creates two types of key. The rest of this page describes Employee list keys; data sync keys are covered in the Data sync guide.

Each key answers only its own endpoints: an Employee list key gets 403 on /api/v1/sync/..., and a data sync key gets 403 on /api/v1/employees.

Creating an API Key

API keys are created in the Hopshift dashboard. You need Group Owner access or Admin access covering every current company in the group.

1. Open the Hopshift dashboard and navigate to Group Settings.
2. Click the API Keys tab.
3. Click Create API Key.
4. Give the key a descriptive name (e.g., "HRIS Sync-Production") and choose the Employee list key type. For a Data sync (read-only) key, follow the Data sync guide.
5. Optionally set an expiry date. Keys without an expiry remain valid until manually revoked.
6. Click Create. The current Read Employees scope is assigned automatically.

Key Format

Hopshift API keys use the hops_ prefix followed by 64 hexadecimal characters:

hops_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Only strings matching this pattern will be accepted as valid Bearer tokens.

Using an API Key

Include the key in the Authorization header of every request using the Bearer scheme:

curl https://hopshift.app/api/v1/employees \
  -H "Authorization: Bearer hops_your_api_key_here"

The header format must be exactly:

Authorization: Bearer hops_<key>

Any other format (including omitting Bearer, using a different prefix, or sending the key in a query parameter) will result in a 401 Unauthorized response.

Scopes

Scopes control which endpoints a key can access. Assign only the scopes a key actually needs.

When a request is made with a valid key that is missing the required scope, the API returns 403 Forbidden:

{
  "error": "Forbidden: missing employees:read scope"
}

Key Lifecycle

Expiry

Keys can optionally be configured with an expiry date at creation time. The selected date is inclusive and uses UTC. Once it has passed, the key is automatically invalidated and all requests using it return 401 Unauthorized. Data sync keys always have an expiry date, at most the same date next year, and can be renewed; see Renew, rotate and revoke.

Revoking a Key

To revoke a key, go to Group Settings → API Keys in the dashboard and click Revoke next to the key. Revocation is immediate: subsequent requests using that key will return 401 Unauthorized.

Revoke keys promptly if:

• A key may have been exposed (leaked in logs, committed to a repository, etc.)
• A key is no longer in use
• A team member with access to the key has left the organisation

Last Used Tracking

The dashboard shows the last time each key was used. Use this to identify stale keys that can safely be revoked.

Rate Limiting

Each Employee list key is limited to 200 requests per minute. This limit is applied per key, not per IP address. Data sync keys have their own limits.

When the rate limit is exceeded the API responds with:

HTTP/1.1 429 Too Many Requests
Retry-After: 14
Content-Type: application/json

{
  "error": "Too many requests"
}

The Retry-After header contains the number of seconds to wait before making another request.

Handling 429 in Your Integration

Implement exponential backoff when you receive a 429 response:

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  retries = 3,
): Promise<Response> {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get("Retry-After") ?? "5", 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRetry(url, options, retries - 1);
  }

  return response;
}

Error Reference

401 Unauthorized

# Example: missing Authorization header
curl https://hopshift.app/api/v1/employees

{
  "error": "Unauthorized"
}

A 401 is returned when:

• The Authorization header is absent
• The header does not start with Bearer hops_
• The key has been revoked
• The key's expiry date has passed

403 Forbidden

{
  "error": "Forbidden: missing employees:read scope"
}

The key is genuine but it was created without the scope required for this endpoint. Create the appropriate integration or personal MCP key; existing keys cannot be upgraded by changing their scope in the dashboard.

500 Internal Server Error

{
  "error": "Internal server error"
}

Something went wrong on our end. If the error persists, please contact Hopshift support.