Quickstart

Goal: from nothing to a successful authenticated call, in the sandbox, in a few minutes.

1. Get your credentials

Partner credentials are issued by Staff & Go — there is no self-service signup yet. Ask your Staff & Go contact for a sandbox partner application. You receive three things:

Credentials are per environment: a sandbox client_id does not authenticate against production.

2. Request an access token

The API is an OAuth 2.0 resource server. Authenticate with the client credentials grant against the Staff & Go authorization server, then send the resulting token as a bearer token.

curl -X POST "https://<authorization-server-host>/realms/staffngo-partners/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

The response contains an access_token and its expires_in lifetime in seconds.

Request a new token shortly before the current one expires rather than after a 401. Tokens are cheap to mint; a retry storm on expiry is not.

Do not request any scope. The ones granted to your application are carried by your credentials, and a token request that asks for nothing gets them all — which is also what keeps your integration working the day an administrator changes what it may read.

If a call is rejected with Scope '…' required, the scope was not granted to you: ask the client company's administrator for it. What you hold is listed by GET /api/v1/client/partner/profile.

3. Make your first call

GET /api/v1/client/partner/profile returns the identity the API resolved for your token. It is the fastest way to confirm that credentials, scopes and tenant binding are all correct.

curl "https://<external-api-host>/api/v1/client/partner/profile" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A 200 response tells you three useful things: which partner you are, which customer tenant your calls act on, and which scopes your token actually carries.

{
  "partnerId": "partner-sample",
  "tenantIds": [
    "4242"
  ],
  "scopes": [
    "external-api",
    "partner:read",
    "payroll:read",
    "payroll:trigger",
    "referentials:read",
    "companies:read",
    "employees:read",
    "employments:read",
    "leaves:read",
    "beta:access"
  ]
}

4. Read the reference

The API reference lists every endpoint with its parameters and responses; the scope each one needs is given in the guide of its theme. You can authenticate there with the same credentials and call endpoints directly from the page.

When something goes wrong