Authentication API

Use the new auth — it works against both APIs

The new API's bearer token (issued by POST /v1/auth/login) authenticates calls against the new API and direct calls to the legacy API. Pass it as OS-ID-TOKEN: <jwt> on legacy /rest/... requests.

Use it for everything. Existing integrations still using legacy session cookies should migrate to this single token; legacy auth stops working on 1 August 2027.

Open POST /v1/auth/login in the new API →

How authentication works

If you're new to the bearer-token + refresh-token pattern, this is the shape of a typical client:

sequenceDiagram
    autonumber
    participant Client
    participant Auth as Oneserve API
    Client->>Auth: POST /v1/auth/login<br/>{user, password}
    Auth-->>Client: {token, refreshToken}
    Note over Client: Store both. Use<br/>token for every<br/>subsequent request.
    Client->>Auth: GET /v1/... (Authorization: Bearer <token>)
    Auth-->>Client: 200 OK
    Note over Client: Token expires (HTTP 401)<br/>Refresh token still valid.
    Client->>Auth: POST /v1/auth/refresh<br/>{user, refreshToken}
    Auth-->>Client: {jwtToken} (new access token)
    Note over Client: Keep the same refreshToken.<br/>Repeat until refresh token<br/>itself expires (~30 days),<br/>then log in again.

1. Log in

curl -sX POST https://api-cans.oneserve.co.uk/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{
    "user": {"companyName": "your-tenant", "userName": "you@example.com"},
    "password": "your-password"
  }'
# → { "token": "<jwt>", "refreshToken": "<refresh>" }

If the account has MFA enabled, login instead returns { challengeName: "SMS_MFA", challengeSession: ... }. Prompt the user for the SMS code and submit it to POST /v1/auth/complete-mfa-login to receive the actual {token, refreshToken}.

For first-time logins (temporary password), use POST /v1/auth/first-time-login to set a new password and receive the tokens in the same response.

2. Use the token on every request

# New API
curl https://api-cans.oneserve.co.uk/v1/jobs \
  -H 'Authorization: Bearer <jwt>'

# Legacy API (direct)
curl https://prod.oneserve.co.uk/rest/workflow/jobs \
  -H 'OS-ID-TOKEN: <jwt>'

Same token, two header names — Authorization: Bearer <jwt> for the new API, OS-ID-TOKEN: <jwt> for direct calls to the legacy stack.

3. Refresh when the token expires

Access tokens have a short lifetime (on the order of an hour). When a request returns 401, exchange the refresh token for a new access token:

curl -sX POST https://api-cans.oneserve.co.uk/v1/auth/refresh \
  -H 'content-type: application/json' \
  -d '{
    "user": {"companyName": "your-tenant", "userName": "you@example.com"},
    "refreshToken": "<refresh>"
  }'
# → { "jwtToken": "<new-jwt>", "payload": { ... } }

Only a new access token comes back — keep using the same refresh token. It stays valid for around 30 days from your original login, so you'll typically refresh many times against the same refresh token before it expires. Once it does (or it gets revoked, see Log out below), call POST /v1/auth/login again to start a fresh session.

4. Log out

curl -X DELETE https://api-cans.oneserve.co.uk/v1/auth/session \
  -H 'Authorization: Bearer <jwt>'

Revokes all sessions for the user — both the access token and any active refresh tokens are invalidated immediately.

More auth endpoints

The new API exposes a richer authentication surface than a single login endpoint: MFA setup, SSO, session management, and bulk admin operations. Browse the full Authentication tag in the new API docs for the complete list.

Next step

With authentication switched over, head back to the migration guide for the recommended order of work and the category-by-category endpoint cards.