Skip to content

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 keyUsername and password
Belongs toA projectA user
Credential you sendThe API key of the projectA token you get with the email address, password and MFA code of the user
LifetimeUntil you generate a new key30 minutes after its last use
Use it forYour systems, scripts and integrationsInteractive 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.

flowchart

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 inactive or ended;
  • 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