Authentication
Each request to a tenant route needs a credential. Send it in the Authorization header:
curl https://app.postoerp.com/api/v1/acme/me \ -H "Authorization: Bearer $POSTO_API_KEY"Choose a credential
Section titled “Choose a credential”| 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.
API keys
Section titled “API keys”An API key secret starts with posto_pk_ (personal key) or posto_sk_ (service key). The API keeps only a hash of the secret.
Make a key in the ERP
Section titled “Make a key in the ERP”- Sign in to the ERP and open the tenant.
- Open System → API keys.
- Select New.
- Type a Name.
- Select the Type: Personal or Service.
- Optional: set Valid to. The key stops at the end of this day.
- Optional: type the Allowed IP addresses. Use addresses or CIDR ranges, separated by commas. Leave it empty to allow every address.
- For a service key, select its Access roles.
- Select Create.
- 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.
Personal and service keys
Section titled “Personal and service keys”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.
Rotate, revoke and delete
Section titled “Rotate, revoke and delete”| 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.”
What a key cannot do
Section titled “What a key cannot do”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/authand the platform routes refuse it with403. - 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.
Server clients
Section titled “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.
Make a server client
Section titled “Make a server client”- Open System → API keys.
- In the section Server clients, select New server client.
- Type a Name.
- Select the Permissions: read or change for each module. Change includes read. You cannot change the permissions after the create.
- Select the Access roles.
- Select Create.
- Copy the Client ID and the Client secret now. The ERP shows the secret only once.
Get a token
Section titled “Get a token”Send the client ID and the secret with HTTP Basic authentication to the token endpoint, /api/auth/oauth2/token:
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" }scopeis optional. Without it, the token gets every permission of the client. A scope that the client does not have getsinvalid_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:
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.
OAuth apps
Section titled “OAuth apps”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.1orhttp://localhoston any port. - A web app is a confidential client with a secret. It returns to an
httpsaddress. - 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_tokenandclient_credentials.
Scopes
Section titled “Scopes”| 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.
Tenant of a token
Section titled “Tenant of a token”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" }}