Skip to content

Getting a credential

From the base URL to a credential that acts on an organization, without any screen of ours.

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, with a name and the RUC of the company as tax_id. The RUC is checked against SUNAT data and cannot change afterwards: a wrong RUC means creating another organization. An organization is a PAIR: the live one and its test twin, each with its own id. The live one is born with its issuer, filled from SUNAT data; the twin is born ready to issue against a simulated provider, with the same RUC (editable there). 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.

Type to search…

↑↓ navigate↵ selectEsc close