# Getting a credential

Everything starts at `GET /v1`: it needs no credential and says how to sign in, where the contract is (`GET /v1/openapi.json`) and the limits. Two kinds of credential exist, both sent as `Authorization: Bearer <credential>`.

## A person's access token (device flow)

A person confirms once in a browser; the client never sees a password.

1. Read `authentication.credentials.person_access_token.device_flow` from `GET /v1`: it holds `device_authorization_endpoint`, `token_endpoint`, `client_id` and the two grant types.
2. POST `client_id` (form-encoded) to `device_authorization_endpoint`. Show `verification_uri_complete` to the person.
3. Poll `token_endpoint` with `grant_type=<device_grant_type>`, `device_code` and `client_id` every `interval` seconds, until it answers the tokens.
4. Use `access_token` as the Bearer credential. When it expires, exchange `refresh_token` at `token_endpoint` with `grant_type=<refresh_grant_type>`.
5. Never print a token. Keep it in the credential store of the operating system.

`GET /v1/me` (any credential) then says who you are. A person belongs to several organizations, so every route that acts on one needs the header `X-Organization: <organization id>`.

## An organization

`GET /v1/organizations` (a person's access token) lists yours; `POST /v1/organizations` (a person's access token; `Idempotency-Key` required) creates one. An organization is a PAIR: the live one and its test twin, each with its own id. The twin is born ready to issue against a simulated provider. Use ITS id until the integration works.

## A service-account key (for a server)

With the person's token and `X-Organization`: `POST /v1/service_accounts` (permission `service_accounts:write`; `Idempotency-Key` required) with a name and the scopes it needs, then `POST /v1/service_accounts/{id}/keys` (permission `service_accounts:write`; `Idempotency-Key` required). The answer carries `secret` ONCE; store it at that moment. A key acts only on its own organization (no `X-Organization` header) and is `sk_test_…` or `sk_live_…` according to the half it was created in.

A key never holds `members:write`: giving people access is a person's decision.

Next: [the first invoice](https://api.invox.page/v1/docs/first-invoice).