API keys
Create an admin API key in the Admin portal, call the platform APIs with it and keep it safe.
Every project has one API key. The API key of a merchant's project is what the merchant uses for the order API. To manage your platform through the platform APIs, you create an admin API key: the API key of a project in a merchant you create for yourself, with permissions on every endpoint.
The admin API key manages your whole platform
It can call every endpoint for every merchant. Use it only in your own systems. Never give it to merchants or other parties.
Before you begin
- You can log in to the Admin portal of your platform, with permission to create merchants and projects.
Create an admin API key
Create the admin merchant
In the Admin portal, go to Merchants and create a merchant. Give it a Company name that makes clear it's yours, such as Admin merchant, and an Email.
Give the merchant permissions
Open the merchant, go to the Permissions tab and select Create Permission. Enter:
- Command path:
/** - Create, Read and Update: on
- Delete: off
Select Create Permission, then Save permissions. These are the base permissions of the merchant: its projects can't get more permissions than this.
Create the admin project
Open the merchant, go to Projects and select Create Project. Enter a Trade Name, such as Admin project, a Website URL and a Description, and set the Status to active-production.
Give the project permissions
Open the project, go to the Permissions tab and create the same permission as on the merchant: Command path / with Create, Read and Update on and Delete off. Select Create Permission, then Save permissions.
In the API, this is the permission:
{
"/**": {
"POST": true,
"GET": true,
"PUT": true,
"DELETE": false
}
}Copy the API key
Open the project and go to the Integration tab. It shows the API key, hidden until you reveal or copy it, and the API endpoint of your platform.
Send the key
Send the API key as the username of HTTP Basic authentication, with an empty password. Most HTTP clients do this for you. With cURL:
curl https://api.example.com/v1/merchants/self/projects/self/ \
--user "$API_KEY:"To build the header yourself, encode the API key followed by a colon (:) with Base64. For the API key hunter2, you encode hunter2: and send Authorization: Basic aHVudGVyMjo=.
The response is your admin project. A 200 OK confirms that the key works. See Health check for more checks.
Keep the key safe
- Store the key in a secret store or the configuration of your server. Never put it in code, a repository, a browser, a mobile app or a support ticket.
- Give each system the key it needs. Use the admin API key only where you manage the platform.
- Use separate projects, and so separate keys, for testing and for live payments.
- Generate a new key when someone who had access leaves, and when you suspect a leak.
Generate a new key
A project has one API key at a time. When you generate a new one, the old key stops working immediately, so update your systems right after.
- Admin portal: open the project, go to the Integration tab, select Edit, then Generate New Api Key.
- API: send a
POSTto theapikeysendpoint of the project, with an empty body:
curl https://api.example.com/v1/merchants/self/projects/$PROJECT_ID/apikeys/ \
--user "$API_KEY:" \
--request POSTThe response holds the new key in apikey, with 201 Created. See Generate a new API key in the API reference.
A project can't change its own permissions, and a user can be denied access to the apikey field with field permissions.
Next steps
- Check your access with the health check.
- Learn how permissions work.