Auth & Key Management

External admins can sign in and manage their own API keys through these endpoints. These are also used by the Dashboard on this docs site.

Sign In

POST /external/v1/auth/signin

Authenticates an external admin and returns a JWT access token.

No API key required — this endpoint uses email/password credentials.

Request Body

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
  "user": {
    "id": "user-uuid",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@partner.com",
    "mustChangePassword": false
  },
  "activeCompany": {
    "id": "company-uuid",
    "name": "Acme Corp"
  },
  "companies": [
    { "id": "company-uuid", "name": "Acme Corp", "privilege": 1 }
  ]
}

curl -X POST "https://api.suprsync.com/external/v1/auth/signin" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@partner.com", "password": "your_password" }'

:::info If mustChangePassword is true, the admin should change their password before proceeding. :::

List API Keys

GET /external/v1/auth/keys

Returns all API keys for the authenticated admin's company.

Requires Authorization: Bearer <accessToken> header.

curl -X GET "https://api.suprsync.com/external/v1/auth/keys" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response

[
  {
    "id": "key-uuid",
    "name": "Payroll Integration",
    "clientId": "api_a1b2c3d4e5f6...",
    "status": "active",
    "lastUsedAt": "2026-02-01T10:30:00.000Z",
    "createdOn": "2026-01-15T08:00:00.000Z"
  }
]

Create API Key

POST /external/v1/auth/keys

Creates a new API key. The clientSecret is returned only once.

Requires Authorization: Bearer <accessToken> header.

Request Body

curl -X POST "https://api.suprsync.com/external/v1/auth/keys" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Payroll Integration" }'

Response

{
  "id": "key-uuid",
  "clientId": "api_a1b2c3d4e5f6...",
  "clientSecret": "sec_x7y8z9..."
}

:::caution Copy the clientSecret immediately. It cannot be retrieved later. :::

Rotate API Key

POST /external/v1/auth/keys/:id/rotate

Generates a new secret for an existing key. The old secret stops working immediately.

curl -X POST "https://api.suprsync.com/external/v1/auth/keys/key-uuid/rotate" \
  -H "Authorization: Bearer eyJhbGciOi..."

Revoke API Key

POST /external/v1/auth/keys/:id/revoke

Permanently revokes an API key. All requests using this key will be rejected.

curl -X POST "https://api.suprsync.com/external/v1/auth/keys/key-uuid/revoke" \
  -H "Authorization: Bearer eyJhbGciOi..."