Authentication API

Posti API uses OAuth 2.0 to provide authorized access to its services


Posti API uses OAuth 2.0 protocol for authentication and authorization. The OAuth 2.0 is a secure and standard authentication protocol that provides sending authorized requests to the Posti API services.

The authentication flow follows these steps:

  1. A client application uses Posti service account username and password via HTTP Basic Authentication to exchange these credentials for an access token
  2. When accessing the protected API service, the client application uses the access token to authenticate

How to get Posti service account

If your business does not have a Posti service account, contact Posti Customer Service to get one. Note that you also need a contract with Posti.

How to test Posti service account

Replace accountname:secret using Posti service account details which Posti has provided to you.

Example request:

curl -H "Accept: application/json" --user "accountname:secret" -d grant_type=client_credentials

Accessing Posti API services

API Endpoints

Environment Protocol Host Path
QA HTTPS /oauth/token
UAT HTTPS /oauth/token
Prod HTTPS /oauth/token
Step 1: Encode username and password

Concatenate the username, a colon character ":", and the password into a single string. After that, Base64 encode the single string.

Base64 encoded value:
Step 2: Get access token from Authorization Server

Before your application can access Posti API services, it must obtain an access token that grants access to the services. A single access token can grant access to multiple services where you have authorization.

The value calculated in Step 1 must be exchanged for a access token by making a HTTP POST request to Authorization Server's access token endpoint. The request must include an Authorization header with the value of "Basic <Base64 encoded value from Step 1>". Url parameter grant_type=client_credentials must also be included to the request.

Access token endpoint:

Example request:

Headers: Accept: application/json
         Authorization: Basic YWNjb3VudG5hbWU6c2VjcmV0

Example response:

{"token_type":"bearer", "access_token": "abc123", "expires_in": 3599}
Step 3: Authenticate API requests with the access token

The access token may be used to issue requests to Posti API endpoints. To use the access token, construct a normal HTTPS request and include an Authorization header with the value of "Bearer <access token value from Step 2>".

Default expiration time is one hour. After that the client application has to request a new access token.

Example request:

Headers: Authorization: Bearer abc123

Status codes

Status Error Message Meaning
401 Unauthorized Bad credentials Wrong username or password or account is locked for 1 hour after 5 invalid login attempts.