Authentication
Authenticate to the platform APIs with an API key, or with a username and password.
Every request to the platform APIs carries credentials, with HTTP Basic authentication (RFC 7617). Most HTTP clients support Basic authentication, so you rarely build the Authorization header yourself.
API keys and user tokens
You authenticate as a project or as a user of a merchant:
| API key | Username and password | |
|---|---|---|
| Belongs to | A project | A user |
| Credential you send | The API key of the project | A token you get with the email address, password and MFA code of the user |
| Lifetime | Until you generate a new key | 30 minutes after its last use |
| Use it for | Your systems, scripts and integrations | Interactive sessions, such as a portal a person logs in to |
For non-interactive use, take an API key. To manage your platform, that's an admin API key.
Either way, you send the key or token as the username and leave the password empty:
curl https://api.example.com/v1/merchants/self/projects/self/ \
--user "$API_KEY:"What a key or token may do depends on its permissions.
When authentication fails
The API responds with 401 Unauthorized when:
- the credentials are missing, unknown or expired;
- the project or user is
inactive; - the merchant is
inactiveorended; - the project only accepts requests from listed IP addresses, and yours isn't one of them.
When a merchant is ending, its projects can't start new payments. Ask your Ginger contact what its API keys and users can still do. See Merchant statuses.
The API responds with 403 Forbidden when the credentials are valid but the permissions don't allow the request.
TLS
The API is only available over HTTPS. HTTP Basic authentication doesn't encrypt the credentials, so TLS protects them on the way. The API accepts TLS 1.2 and TLS 1.3; older versions of TLS and SSL are refused. Most modern HTTP clients support TLS 1.2 by default; update old libraries and runtimes that don't.
Next steps
- Create an admin API key.
- Log users in with a username and password.
- Learn how permissions work.