Authentication API

Overview

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

NOTE! When using the Posti service account, please make sure not to store secrets (including API keys, passwords, authorization tokens, encryption keys, certificates and other credentials) in plain text on public resources that are accessible to anyone on the Internet, such as public Postman collections or workspaces, public GitHub repositories and other public resources. Use only private Postman collections and workspaces, private GitHub repositories, etc. that only authorized users can access.

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" https://oauth2.posti.com/oauth/token -d grant_type=client_credentials
	    

Accessing Posti API services

API Endpoints

Environment	Protocol	Host	Path
QA	HTTPS	oauth2.barium.posti.com	/oauth/token
UAT	HTTPS	oauth2.barium.posti.com	/oauth/token
Prod	HTTPS	oauth2.posti.com	/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.

Credentials:

accountname:secret

Base64 encoded value:

YWNjb3VudG5hbWU6c2VjcmV0

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:

https://oauth2.posti.com/oauth/token

Example request:

POST https://oauth2.posti.com/oauth/token?grant_type=client_credentials
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:

GET https://api.posti.fi/estimation/v1/00100/FI/99710/FI/2103?time=2017-10-03T09:00:00.000%2B0300
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.