Skip to content

Authentication

InPost REST APIs use OAuth 2.1 access tokens to authenticate requests. Your access token authorizes you to use the InPost REST API server. To call a REST API in your integration, you'll need to exchange your client ID and client secret for an access token. You can make the API call in any programming language.

How to generate client ID and client secret?

Please contact your Integration Team with requested scopes. We are in-progress of enabling markets with a self-service solution at https://merchant.inpost-group.com

Available Scopes:

  • api:points:read
  • api:shipments:read
  • api:shipments:write
  • api:returns:read
  • api:returns:write
  • api:one-time-pickups:read
  • api:one-time-pickups:write
  • api:tracking:read

Environments

Supported OAuth 2.1 flows

Option 1: Client Credentials Flow - RFC6749

This flow is best suited for Machine-to-Machine (M2M) applications, such as CLIs, daemons, or backend services, because the system must authenticate and authorize the application backend, not a user. The following examples show you how to get your access token using cURL. This flow has the limitation that we cannot use it where one app is working on behalf of multiple users. It is strictly correlated with a single application, and we recommend it for simple integrations.

curl -X POST 'https://stage-api.inpost-group.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'client_secret=your_client_secret' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=openid%20api:points:read%20api:shipments:write'

Make sure you add all relevant scopes during token creation. How it would look in Postman:

Generate an access token from Postman

InPost Auth API returns an access token, type and number of seconds the access token is valid.

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5c...",
    "token_type": "Bearer",
    "expires_in": 599
}

When you make calls to a REST API, include the access token in the authorization header: -H Authorization: Bearer ACCESS-TOKEN. When your access token expires, call {host}/oauth2/token again to request a new access token.

Option 2: Authorization Code Flow with Proof Key for Code Exchange (PKCE) - RFC7636

This flow is best suited for brokers applications, which will implement log in with an InPost Account, so users can provide consent to a broker's application to perform actions on their behalf.

Our API is compliant with OAuth 2.1, so we required using PKCE in this authorization method. The Authorization Code Flow with Proof Key for Code Exchange (PKCE) is an extension that enhances the security of the authorization code flow. PKCE is designed to protect authorization codes from interception attacks.

Implementation | Step 1: Generate Code Verifier and Code Challenge

Before initiating the authorization request, generate a code verifier and code challenge.

  • Code Verifier: A high-entropy cryptographic random string.
  • Code Challenge: A base64-url-encoded SHA256 hash of the code verifier.

Sample Python code for generating PKCE keys

import base64
import hashlib
import os

def generate_code_verifier():
    return base64.urlsafe_b64encode(os.urandom(32)).rstrip(b'=').decode('utf-8')

def generate_code_challenge(verifier):
    challenge = hashlib.sha256(verifier.encode('utf-8')).digest()
    return base64.urlsafe_b64encode(challenge).rstrip(b'=').decode('utf-8')

code_verifier = generate_code_verifier()
code_challenge = generate_code_challenge(code_verifier)

print("Code Verifier:", code_verifier)
print("Code Challenge:", code_challenge)

Implementation | Step 2: Authorization Request

The next step is redirect user to our login page with following parameters. You need to decide which scopes are needed, so user could see the list and grant your application the access.

    curl -X GET 'https://stage-account.inpost-group.com/oauth2/authorize?response_type=code
    &redirect_uri=https://your-app.com/callback
    &client_id=your_client_id
    &scope=openid%20api:points:read%20api:shipments:write
    &code_challenge=abc123def456ghi789
    &code_challenge_method=S256'

Implementation | Step 3: User logs in and provides consent for an external application

User login screen User's consent screen

Implementation | Step 4: Exchange authorization code to receive refresh and access token

On redirect uri provided in previous step we receive one-time code that we need to exchange to obtain refresh and access token.

curl -X POST 'https://stage-api.inpost-group.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'client_secret=your_client_secret' \

--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=https://your-app.com/callback' \
--data-urlencode 'code=b9e50bd4-5ab0-4701-8c73-69466aa7ba21.......' \
--data-urlencode 'code_verifier=WIFPE6ylf8eGdggfT2r9zdXL8duZFrUNo0tbbHxolI4'

Response:

{
    "access_token": "eyJraWQiOiJnaXAtZGV2LTEiLCJ...",
    "refresh_token": "9-BoEWR78xZY1mJJ3cnpM...",
    "scope": "api:points:read api:shipments:write",
    "token_type": "Bearer",
    "expires_in": 299
}

Implementation | Step 5: Access token expiration

If your access_token will expire, your system need to exchange refresh_token to get a new access token.

curl -X POST 'https://stage-api.inpost-group.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'client_secret=your_client_secret' \

--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=WIFPE6ylf8eGdggfT2r9zdXL8duZFrUNo0tbbHxolI4...'

Example requests with Bearer token

curl -X GET 'https://stage-api.inpost-group.com/location/v1/points' \
--header 'Authorization: Bearer {token}'