Skip to content

Authentication

Each request to a tenant route needs a credential. Send it in the Authorization header:

Terminal window
curl https://app.postoerp.com/api/v1/acme/me \
-H "Authorization: Bearer $POSTO_API_KEY"
Credential For Acts as How you get it
Personal API key Your own scripts You, with your role and access roles ERP, System → API keys
Service API key A server or an integration of the tenant Its own user, with the access roles that you give it ERP, System → API keys
Server client A server that uses OAuth (client credentials) Its own user, with access roles and module scopes ERP, System → API keys → Server clients
OAuth app An app that acts for a signed-in user, such as the PoS The user who signs in, limited by the token scopes A Posto platform administrator registers it

Use an API key for scripts and servers of one tenant. Use OAuth when a person signs in to your app.

Each credential works in one tenant. A request to another tenant gets 403.

An API key secret starts with posto_pk_ (personal key) or posto_sk_ (service key). The API keeps only a hash of the secret.

  1. Sign in to the ERP and open the tenant.
  2. Open System → API keys.
  3. Select New.
  4. Type a Name.
  5. Select the Type: Personal or Service.
  6. Optional: set Valid to. The key stops at the end of this day.
  7. Optional: type the Allowed IP addresses. Use addresses or CIDR ranges, separated by commas. Leave it empty to allow every address.
  8. For a service key, select its Access roles.
  9. Select Create.
  10. Copy the Key secret now. The ERP shows it only once.

Keep the secret in a secret store or an environment variable. Do not put it in source code.

A personal key acts as its owner. It has the role and the access roles of the owner in the tenant. It stops when the owner leaves the tenant. A member can make a personal key for themselves.

A service key has its own user in the tenant. That user has only the access roles that you give the key. The records that the key creates show the key as their author. To make a service key, you need the write right on the feature API keys. Owners and admins have it. You can give a service key only the rights that you have.

Action Result
Rotate The key gets a new secret. The ERP shows it once. The old secret works for 24 more hours. A second rotation in these 24 hours stops the first old secret.
Revoke The key stops at once. The key stays in the list as revoked. A revoked key cannot be rotated.
Delete The key stops at once and leaves the list.

A request with a revoked, expired, deleted or unknown key gets 401 with the message “Invalid API key.”

A key has the access of its user, but some actions need a person who signs in:

  • A key cannot list, make, change, rotate or delete API keys or server clients.
  • A key cannot create a user with a password. It can add a user who already exists to the tenant.
  • A key works only on the tenant routes under /api/v1/<tenant>/. The sign-in endpoints under /api/auth and the platform routes refuse it with 403.
  • A key works only from its allowed IP addresses, if the list is not empty. Another address gets 403.
  • A personal key of a platform administrator has no administrator rights. It has only the rights of a member of the tenant.

The demo tenant refuses the creation of API keys and server clients.

A server client is an OAuth client of your tenant. It uses the client credentials grant. Use it when your server must get its tokens with OAuth. Like a service key, it has its own user and the access roles that you give it.

  1. Open System → API keys.
  2. In the section Server clients, select New server client.
  3. Type a Name.
  4. Select the Permissions: read or change for each module. Change includes read. You cannot change the permissions after the create.
  5. Select the Access roles.
  6. Select Create.
  7. Copy the Client ID and the Client secret now. The ERP shows the secret only once.

Send the client ID and the secret with HTTP Basic authentication to the token endpoint, /api/auth/oauth2/token:

Terminal window
curl https://app.postoerp.com/api/auth/oauth2/token \
-u "$POSTO_CLIENT_ID:$POSTO_CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope=sales:read
{ "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "sales:read" }
  • scope is optional. Without it, the token gets every permission of the client. A scope that the client does not have gets invalid_scope.
  • The token lives 1 hour. There is no refresh token: ask for a new token when the old one expires.
  • A request must pass the access roles of the client and the scopes of the token.

Send the token as a bearer token:

Terminal window
curl https://app.postoerp.com/api/v1/acme/sales/invoices \
-H "Authorization: Bearer $POSTO_ACCESS_TOKEN"

A route that needs a scope that the token does not have gets 403 with “The OAuth token has no scope for this action.”

Select New secret to rotate the secret of a server client. The old secret works for 24 more hours. You can also disable, enable and delete a server client. A disabled client gets no new token, and its tokens stop working.

An OAuth app acts for a user who signs in. The PoS desktop app is one. Read PoS integration for its sign-in flow.

  • Only a Posto platform administrator registers an OAuth app. Dynamic client registration is off.
  • A native app is a public client. It uses PKCE (S256) and returns to http://127.0.0.1 or http://localhost on any port.
  • A web app is a confidential client with a secret. It returns to an https address.
  • The app finds its endpoints in the discovery document at the root of the issuer: /.well-known/openid-configuration.
  • The grants are authorization_code, refresh_token and client_credentials.
Scope Gives
openid, profile, email, offline_access OpenID Connect data and a refresh token. No module data.
<module>:read Reads in the module, for example sales:read
<module>:write Reads and writes in the module, for example sales:write

The modules are inventory, retail, sales, purchasing, pricing, payroll, assets, finance, cash, masters and system. The activity log has only activity:read.

A request needs both the role of the user and the scope of the token. A token never gets platform administrator rights.

When a user is a member of more than one tenant, the sign-in asks for a tenant. The token works only in that tenant. The token answer names it:

{
"access_token": "…",
"refresh_token": "…",
"token_type": "Bearer",
"expires_in": 3600,
"tenant": { "id": "…", "slug": "acme", "name": "Acme Trade" }
}