Authentication

The Envoi API uses OAuth 2.0 client credentials. You exchange a client ID and secret for a token, and send the token with every call.

Create an API client

Only the company’s owner and admins can create API clients.

Go to API clients

Open Settings → API clients in Envoi and choose Create API client.

Choose a type

Accounting client comes set up with access to invoices, customers, journal entries and reports. Advanced setup lets you choose the environment and exactly which permissions the client gets.

Copy the secret

The secret is shown once, and Envoi does not store it. Copy it right away and keep it safe. You also need the client ID and account ID.

The secret gives access to the company’s data. Never put it in code that runs in a browser or an app, and never in a public repository.

Get a token

curl https://api.envoi.no/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d audience=https://api.envoi.no/v1/accounts/P11112001

Field	Value
`grant_type`	Always `client_credentials`
`audience`	`https://api.envoi.no/v1/accounts/{account ID}`. The account ID decides the environment: `P…` is production, `T…` is test
`client_id`, `client_secret`	In the `Authorization: Basic` header (as above) or in the form, not both

The response:

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "bilag:read clients:write invoices:write reports:read"
}

The token lasts 15 minutes. There is no refresh token: request a new one with the same credentials when it expires.

Use the token

curl https://api.envoi.no/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN"

A token covers one company in one environment. Which company a call acts on is decided by the token and cannot be changed with a header or in the URL.

Permissions

Permissions are written as resource:level, for example invoices:write. Levels build on each other: admin includes write, and write includes read.

Permission	Gives access to
`invoices:read`	Listing and reading invoices
`invoices:write`	Creating, sending and recording payments
`clients:read`	Listing and reading customers
`clients:write`	Creating customers
`bilag:read`	Chart of accounts and journal entries

If the client lacks the permission an endpoint needs, you get 403 insufficient_scope.

Changes apply immediately

Envoi checks the client against the database on every call, not just the token:

Delete the client, and its tokens are refused on the next call.
Rotate the secret, and tokens issued with the old one are refused on the next call.
Remove a permission or an environment, and it applies from the next call.

Token endpoint errors

The token endpoint answers with { "error": "<code>" }, as OAuth 2.0 describes.

Status	`error`	When
400	`invalid_request`	Not a form, or the secret both in the header and in the form
400	`unsupported_grant_type`	`grant_type` is not `client_credentials`
400	`invalid_target`	The `audience` is malformed, names another company, or an environment the client has no access to
401	`invalid_client`	Unknown client, wrong secret or deleted client. The same answer for all three
403	`access_denied`	The company is being closed
429	`rate_limited`	Too many attempts: 60 a minute per IP address and 30 a minute per client. `Retry-After` says when to try again

Get started

Authentication

Invoices

Customers

Accounting

Authentication

Create an API client

Get a token

Use the token

Permissions

Changes apply immediately

Token endpoint errors

​Create an API client

​Get a token

​Use the token

​Permissions

​Changes apply immediately

​Token endpoint errors

Create an API client

Get a token

Use the token

Permissions

Changes apply immediately

Token endpoint errors