Basic authentication with client credentials

The Pismo platform supports server-to-server (S2S) authentication using stored credentials. This is similar to a username/password system, except it uses a server_key and a secret_key.


Authentication tokens

For information about generating access tokens, see Generating a JWT.

Requests that involve a specific account require an access token generated using anaccount_id.

Requests that involve an external account ID require an access token generated using anexternal_account_id.

The Pismo platform's Passport API allows server-to-server authentication, so a proxy server can execute some operations. For example, in the case of a person using an app on a mobile device or an operator using a CRM system, the authentication process should go through a proxy server.

Generating authentication keys

Before you can log in to the Pismo platform, you need a server key (server_key) and a secret key (secret_key). In Pismo Console, click Create key. This generates both keys. You must be an admin to use Pismo Console.


Secret key is displayed only once

After you generate your secret key, you should save it somewhere. Otherwise, you'll have to generate a new one the next time you need to provide it.

Initial authentication

When first logging in from an external server, you need to send the Pismo platform a request to create an access token. Pismo will return a JSON Web Token (JWT). You must include your server_key and secret_key in the body of the request.

If you intend to make calls on behalf of a specific account, you must also include the corresponding account identifier (account_id). If you provide an account identifier, subsequent calls can only access resources that belong to that particular account.

You can find a complete list of the endpoints that you can use for requests in the API Reference. For a list of the endpoints that require the account identifier, see Endpoints that require an account-specific token.

To request an access token, use the following endpoint.

Get basic authentication access token
Request body:

  "server_key": "<server_key_provided>",
  "secret_key": "<server_secret_key_provided>",
  "account_id": <account_holder_identifier>

The following code shows an example of a response body for this request. It includes an access token (token), which you can use as an authorization header in future requests.

  "server_key": "<server_key_provided>",
  "tenant": "<tenant>",
  "program_ids": [],
  "roles": [

Renewing an expired token

The access token has a predefined lifetime. There is an exp field in the JWT that contains the date/time of expiration in Unix Epoch time. After the access token expires, the Pismo platform rejects additional requests. If you make a request using an expired token, the request returns Unauthorized. You should check for this message in your code and request a new access token when you receive it.


You can use the JWT Debugger website to view the fields in a JWT. Holding the mouse pointer over the decoded exp value displays it as a human-readable date/time.

If you need to access the field values in your code, see Parsing the JWT.