Authentication

Every address except the eight listed at the bottom of this page requires a credential. There are two accepted kinds, and they are interchangeable everywhere: a bearer token minted by Skopea, or an AWS SigV4 identity proof for callers that already hold AWS credentials.

Authorization: Bearer <access_token>

Which flow do I want?

You are	Use
A script or a CI job, with a password	Password
A CLI on a human's laptop	Device flow
A tool already holding an AWS SSO session	SSO credential exchange
A browser that has already completed SAML SSO	Session exchange
Any of the above, but you need a different organization	Organization token

All of them end the same way: an access_token you put in the Authorization header, and a refresh_token you keep for when it expires.

Password

POST /api/v1/auth/tokens/password — public.

curl -sX POST "$SKOPEA_API/api/v1/auth/tokens/password" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}'

{
  "data": {
    "access_token": "eyJhbGciOi…",
    "refresh_token": "eyJhbGciOi…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": { "email": "you@example.com", "…": "…" }
  },
  "error": null,
  "metadata": { "requestId": "…", "timestamp": "…" }
}

This is the flow for deployments that do not use SSO. On an SSO deployment the account may simply have no password to check.

Device flow

POST /api/v1/auth/device-codes then POST /api/v1/auth/tokens/device-code — both public. This is RFC 8628, and it is what skopea auth login uses: the machine that needs the token never sees the credential.

1. Ask for a code.

curl -sX POST "$SKOPEA_API/api/v1/auth/device-codes" \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"skopea-cli"}'

You get back two halves. user_code is the short string the human types; device_code is the secret your program keeps and polls with. Send the human to verification_uri_complete, which already carries the code.

2. The human approves, from a browser where they are logged in. That browser calls POST /api/v1/auth/device-codes/actions with {"action":"approve","user_code":"ABCD-1234"}. Approving binds the device code to *their own* identity — which is why no special permission is required to do it, and why the resulting token can never exceed what that person can already do.

3. Poll, no faster than the interval seconds you were given.

curl -sX POST "$SKOPEA_API/api/v1/auth/tokens/device-code" \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code",
       "device_code":"'"$DEVICE_CODE"'"}'

This one endpoint does not use the Skopea envelope. While the code is pending, denied or expired, it answers 400 with the OAuth spelling — {"error":"authorization_pending","error_description":"…"} — because that is what RFC 8628 clients expect. Poll until error stops being authorization_pending.

SSO credential exchange

POST /api/v1/auth/tokens/sso-credentials — public.

Hand Skopea a live set of AWS credentials; it calls STS GetCallerIdentity with them and derives your e-mail from the assumed-role ARN.

curl -sX POST "$SKOPEA_API/api/v1/auth/tokens/sso-credentials" \
  -H 'Content-Type: application/json' \
  -d "{\"aws_access_key_id\":\"$AWS_ACCESS_KEY_ID\",
       \"aws_secret_access_key\":\"$AWS_SECRET_ACCESS_KEY\",
       \"aws_session_token\":\"$AWS_SESSION_TOKEN\"}"

Know what this trusts. Any AWS identity whose ARN yields an e-mail Skopea recognises can obtain a token this way. The strength of the flow is the strength of your Identity Center session-name convention.

SigV4, without the exchange

If you would rather not hand over credentials at all, sign each request instead: Skopea also accepts a Vault-style SigV4 identity proof in the Authorization header. The client signs a GetCallerIdentity request, the server forwards it to STS, and nothing is stored. No token, no refresh, no logout — the credential is the AWS session itself.

Session exchange

POST /api/v1/auth/tokens/session — send an empty body, with the SAML/SSO cookie your browser already holds. The server reads the identity the SSO authorizer put on the request; the caller cannot name someone else. This is how the web app turns a completed SAML login into an API token.

Organization token

POST /api/v1/auth/tokens/organization, body {"target_org_id":"<uuid>"}.

Note the shape: an id, not the slug you use in paths. Get it from GET /api/v1/me/orgs, which lists the organizations your identity can reach.

The response adds org_slug and org_role to the usual grant. Your previous token is not revoked — this mints a second one, so a tool can hold tokens for several organizations at once.

Refreshing, checking, revoking


Refresh	`POST /api/v1/auth/tokens/refresh-token` with `{"grant_type":"refresh_token","refresh_token":"…"}`.
Who am I	`GET /api/v1/auth/identity` — the identity behind the credential. Use this, not `/health`, to test that a token works.
Is it still good	`GET /api/v1/auth/identity/status`.
Log out	`POST /api/v1/auth/tokens/actions` with `{"action":"revoke"}`. It revokes exactly the token in your `Authorization` header — there is no surface for revoking anyone else's.

The eight public addresses

Everything else answers 401 without a credential.

Address	Why it is public
`GET /api/v1/health`	Liveness probe. Returns status, service name and time — nothing about your deployment.
`GET /api/v1/config/public`	Branding for the login page, which by definition renders before you log in.
`POST /api/v1/auth/device-codes`	The caller has no credential yet. The code it mints is worthless until a logged-in human approves it.
`POST /api/v1/auth/tokens/device-code`	The guard is possession of the `device_code` secret.
`POST /api/v1/auth/tokens/password`	The guard is the password.
`POST /api/v1/auth/tokens/sso-credentials`	The guard is STS.
`GET /api/v1/platform/setup`	Reports one boolean: whether this deployment still has no administrator.
`POST /api/v1/platform/setup`	Creates the first administrator. It is refused the moment one exists — that check is the only thing standing between a fresh deployment and anybody.