Franpos DevelopersDevelopment

Authentication

The API accepts two kinds of credential. OAuth 2.0 client credentials is the recommended way for new integrations. API keys keep working exactly as they do today.

OAuth 2.0 (recommended)

  1. Get a credential: an account owner creates one in Franpos. You get a client_id and a client_secret. The secret is shown once.
  2. Exchange them for an access token. Tokens last 60 minutes.
  3. Send the token as a bearer token on every API call.
curl -X POST https://devdeveloper.franpos.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d "scope=customers:read"
{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "customers:read"
}
curl https://publicapi.franpos.com/api/getLocationsInfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

You can also send the client credentials with HTTP Basic authentication instead of in the body. The scope parameter is optional: leave it out to get every scope the credential holds, or ask for fewer to narrow the token.

Request a new token before the old one expires. Do not request one per call: the token endpoint is rate limited (see Limits).

Rotating a secret

Choose Rotate secret on the credential in Franpos (Settings, Get API). The new secret is shown once, and the old one keeps working so you can switch without downtime. When your integration is on the new secret, choose Finish rotation and the old one stops.

Revoking a credential

Revoking takes effect within about a minute, and it also stops tokens the credential already issued. You do not have to wait for them to expire.

Restricting by address

A credential can list the addresses it may be used from. Token requests and API calls from anywhere else are refused.

API keys (existing integrations)

Your current key is unchanged and will keep working. Send it in the Authorization header:

curl https://publicapi.franpos.com/api/getLocationsInfo \
  -H "Authorization: Token YOUR_API_KEY"

The scheme word (Token, Bearer) is ignored. A key may be followed by :LOCATION_ID to act as one of a reseller's merchants. The key can also be passed as a ?token= query parameter, but we recommend against it: query strings end up in logs and browser history.

An API key holds every scope. If you want an integration limited to specific operations, use an OAuth credential.

Which one am I using?

A value that starts with eyJ and has two dots in it is an access token. Anything else is treated as an API key.