Authentication

Authenticate requests to the Unzer API.

Overview

The Unzer API uses bearer token authentication over HTTPS. To authenticate, you first exchange your private key for a short-lived access token, then include that token in the Authorization header of your API requests.

Private key

Your private key allows you to identify yourself while sending Unzer API requests on the server side. Your private key has multiple permissions, so be sure to keep it safe. You should never make your private key accessible on the web.

If your private key is compromised, please contact our support team immediately to change it.

Public key

Your public key allows you to identify yourself while sending Unzer API requests on the client side. This is utilized when integrating using Unzer UI components.

Authentication

Authenticate your API requests in two steps: first obtain an access token, then use it as a bearer token.

Step 1: Get an access token

Send an empty POST request to the token endpoint, authenticating with your private key using HTTP Basic Auth:

cURL

cURL

Copy

curl https://token.upcgw.com/v1/auth/token \
  -X POST \
  -u s-priv-xxxxxxxxxx:

The response contains your access token:

{
  "accessToken": "eyJraWQiOiJhbGlhcy9jb25uZWN0aXZpdHktdjItdG9rZW4ta21zIiwiYWxnIjoiUlMyNTY..."
}

• Cache the token on your server and reuse it for multiple requests. Do not request a new token for every API call.
• A requested token is currently valid for 7 minutes, but this may change. Check the exp claim of the JWT to determine the actual expiry time.
• On a 401 Unauthorized response, request a new token and retry the call.
• There is a rate limit of 2 token creations per second.

Step 2: Use the bearer token

Include the access token in the Authorization header of your API requests:

cURL

cURL PHP SDK Java SDK JavaScript

Copy

curl https://api.unzer.com/v1/keypair \
  -H 'Authorization: Bearer <access_token>'

PHP SDK

cURL PHP SDK Java SDK JavaScript

Copy

// You do not need to handle tokens manually because it is done for you by the SDK.
// You can just create the Unzer object and pass your private key as parameter one
$unzer = new Unzer('s-priv-xxxxxxxxxx', SupportedLocale::GERMAN_GERMAN);

Java SDK

cURL PHP SDK Java SDK JavaScript

Copy

// Use the public key when calling Unzer API on the client side.
var unzer = new Unzer('s-pub-xxxxxxxxxx');

JavaScript

cURL PHP SDK Java SDK JavaScript

Copy

// Use the public key when calling Unzer API on the client side.
var unzer = new Unzer('s-pub-xxxxxxxxxx');

If you are using one of our SDKs, the token handling is done automatically as long as you are reusing the Unzer instance. You do not need to manage tokens manually.

Legacy: Basic Authentication

Basic Authentication is a legacy method. We recommend migrating to bearer token authentication described above.

HTTP basic authentication requires a username and password. In the Unzer API, the username is your API key, and the password is empty. To provide an empty password, add a colon (:) at the end of your key. Remember to encode your API key with a Base64 encoder.

curl https://api.unzer.com/v1/keypair \
  --header "Authorization: Basic cy1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxOg=="

Unzer API keys

If you request for a test account, you will receive two sandbox API keys:

• Your sandbox public key (for example, s-pub-xxxxxxxxxx)
• Your sandbox private key (for example, s-priv-xxxxxxxxxx)

Sandbox keys allow you to make test transactions.

After signing your Unzer contract, you get your production API keys:

• Your production public key (for example, p-pub-xxxxxxxxxx)
• Your production private key (for example, p-priv-xxxxxxxxxx)

Your API keys are configured with permissions valid for your specific account. They are specific to you as a merchant.

Depending on the resource and method used, you either need your public key or your private key to authenticate your request. For details on which features require a public key or a private key, as shown in the following table.

See also

Check your key configuration:

• Direct API integration