Skip to content

Log in with a username and password

Get a token with a user's email address and password, with multi-factor authentication, trusted devices and password reset.

Use this for interactive sessions, such as a portal your users log in to. Your application exchanges the email address, password and, when enabled, multi-factor authentication (MFA) code of a user for a token: a temporary key it sends with the next requests. For your own systems, use an API key instead.

Get a token

Send the email address and password to the tokens endpoint. This request needs no authentication.

curl https://api.example.com/v1/tokens/ \
  --header "Content-Type: application/json" \
  --data '{
    "email": "ops@example.com",
    "password": "correct-Horse-battery-7"
  }'

The response is the token, with 201 Created:

{
  "id": "4c0ffee5c0ffee5c0ffee5c0ffee5c0f",
  "expiration_period": "PT30M",
  "status": "active",
  "permissions": {
    "/merchants/self/": { "GET": true },
    "/orders/**": { "GET": true }
  }
}

The response is shortened. The permissions are the combined permissions of the user and its roles. Use them to show only what the user may do. See Create a token in the API reference for all fields.

Use the token

Send the id of the token as the username of HTTP Basic authentication, with an empty password:

curl https://api.example.com/v1/merchants/self/users/self/ \
  --user "$TOKEN:"

A token expires 30 minutes after its last use: every request with the token extends it. A user has one active token at a time: a new login ends the earlier tokens of the user.

Multi-factor authentication

Users can protect their account with MFA, with an authenticator app or with codes by SMS. Users enrol themselves, see Set up MFA.

When a user has MFA, a login with only the email address and password fails with 400 Bad Request and the error type MFARequiredError. The response lists the methods of the user in mfa_methods.

If you don't know whether a user has MFA, log in with the email address and password first, and ask for the code when you receive this error. When SMS is the only method of the user, Ginger sends the code by SMS straight away. When the user also has an authenticator app, no SMS is sent: ask for the code from the app, or log in again with force_send_sms set to true to send one.

Then log in again with the code in mfa_token:

curl https://api.example.com/v1/tokens/ \
  --header "Content-Type: application/json" \
  --data '{
    "email": "ops@example.com",
    "password": "correct-Horse-battery-7",
    "mfa_token": "123456"
  }'

Trusted devices

A trusted device lets a user skip the MFA code on later logins from that device for 14 days. Let the user choose this, for example with a checkbox, and send generate_trusted_token set to true with the MFA code. The token in the response then has a trusted_token.

Store the trusted token on the device, for example in an HTTP-only cookie, and send it as trusted_token with the next login instead of an MFA code.

Every login with a trusted token returns a new trusted_token that replaces the old one: store it. This limits the damage when a trusted token leaks. The 14 days count from the first login on the device and don't restart. When the trusted token has expired, the login fails with an MFARequiredError again.

Ginger revokes all trusted tokens of a user when the user changes or resets their password, and when they enrol in a new MFA method.

Errors

A failed login returns 400 Bad Request. The error.type tells you what to do:

TypeMeaning
InvalidPasswordErrorThe email address or password is wrong, or the user or its merchant isn't active. The response doesn't say which.
MFARequiredErrorThe user has MFA. Ask for a code, see Multi-factor authentication.
InvalidMFATokenThe MFA code is wrong or expired.
BackOffLimitReachedToo many failed attempts: the account is locked temporarily. Try again later.

Reset a password

Users who forgot their password reset it through your application. Ginger doesn't send the email: your application does.

Request a password reset token

When a user asks for a reset, request a password reset token with their email address. Authenticate with an API key that has permission for POST /tokens/password-reset/. Ask your Ginger contact which API key to use for this call.

curl https://api.example.com/v1/tokens/password-reset/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{ "email": "ops@example.com" }'

The token is valid for 30 minutes, and only allows setting the password of this user. Requesting it ends the active sessions and trusted devices of the user. See Create a password reset token in the API reference.

When the email address is unknown, or the user or its merchant isn't active, you get an error and no token: don't send an email. Show the user the same message either way, so your application doesn't reveal which email addresses exist.

Send the user an email with a link to your password reset form. Put the id of the token in the link.

Set the new password

When the user submits the form, set the new password with the token id as the credentials:

curl https://api.example.com/v1/merchants/self/users/self/password/ \
  --user "$RESET_TOKEN:" \
  --header "Content-Type: application/json" \
  --data '{ "new": "new-Correct-horse-8" }'

The API responds with 204 No Content. The new password must meet the password policy of your platform. See Reset a password in the API reference.

Revoke the reset token

Revoke the token after use, see Revoke a token. A successful login of the user also ends it.

Revoke a token

To log a user out, revoke their token. Authenticate with the token itself:

curl https://api.example.com/v1/tokens/$TOKEN/ \
  --user "$TOKEN:" \
  --request DELETE

The response is the token with the status inactive. To check a token, and extend it, retrieve it with GET on the same URL. See Revoke a token and Retrieve a token in the API reference.

Next steps