Auth

Sign your customers up and log them in on your own website, with an email and a password. Your server makes these calls with your API key and gets the customer's session back. The customer joins your store as if they had signed up in your salon, and shows in your Bench like any other customer. The API comes with the Retail plan.

Register

Creates the customer's account and signs them in.

POSThttps://api.diamra.com/v1/auth/register

Parameter	What it is
email	Required. The customer's email address.
password	Required. At least 6 characters and at most 72.
name	Optional. The name your store sees for the customer, up to 100 characters.

RequestShell

curl https://api.diamra.com/v1/auth/register \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "password": "their-password", "name": "Jane Doe" }'

ResponseHTTP

HTTP/2 201
content-type: application/json
request-id: req_3b1f9a07c2e84d55

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "expires_at": 1762207200,
  "refresh_token": "kq3xv7j2lm4p",
  "customer": {
    "id": "6f1c2a9e-4b7d-4e2a-9c3f-8d5e1b2a7c40",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "access": "granted"
  }
}

An email that already has an account answers 409 email_exists, even when the customer never signed up on your website. Log them in instead.

Log in

Signs in a customer who has a password. The answer is the same session as Register's, with a 200.

POSThttps://api.diamra.com/v1/auth/login

Parameter	What it is
email	Required.
password	Required.

RequestShell

curl https://api.diamra.com/v1/auth/login \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "password": "their-password" }'

A wrong password and an email without an account both answer 400 invalid_credentials, so nobody can use this call to learn which emails have accounts. Customers who signed up in your salon with Google or a phone number have no password until they set one with Reset a password.

Refresh

An access token lasts an hour. Before it runs out, trade the refresh token for a new session. Each refresh token works once: keep the new one from every answer. A used one answers 400 refresh_token_invalid, and the customer has to log in again.

POSThttps://api.diamra.com/v1/auth/refresh

Parameter	What it is
refresh_token	Required. The refresh token from the last session.

RequestShell

curl https://api.diamra.com/v1/auth/refresh \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "kq3xv7j2lm4p" }'

Log out

Ends the session the refresh token belongs to. The customer stays signed in anywhere else, such as your salon or another device. The refresh token stops working at once. The access token runs out on its own within the hour, so drop it as well.

POSThttps://api.diamra.com/v1/auth/logout

Parameter	What it is
refresh_token	Required. The refresh token of the session to end.

RequestShell

curl https://api.diamra.com/v1/auth/logout \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "kq3xv7j2lm4p" }'

The answer is { "logged_out": true } with a 200, also for a refresh token that no longer works: that session is over already.

Reset a password

Two calls. The first emails the customer an 8-digit code, signed with your store's name. The second takes the code and the new password, and answers the session, as Log in does. Customers who signed up with Google can set a first password this way, since their account has an email address.

POSThttps://api.diamra.com/v1/auth/reset-password

Parameter	What it is
email	Required.

RequestShell

curl https://api.diamra.com/v1/auth/reset-password \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com" }'

The answer is a 202 with an empty object, whether or not the email has an account, so nobody can use this call to learn which emails have one. A code lasts an hour. Diamra sends at most one email a minute to an address, so asking again sooner leaves the first code working.

POSThttps://api.diamra.com/v1/auth/reset-password/confirm

Parameter	What it is
email	Required.
code	Required. The 8 digits from the email, as a string.
password	Required. The new password: at least 6 characters and at most 72.

RequestShell

curl https://api.diamra.com/v1/auth/reset-password/confirm \
  -H "Authorization: Bearer $DIAMRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "code": "48201937", "password": "their-new-password" }'

A code works once. A wrong or used code answers 400 code_invalid. A password that is too short answers 400 password_too_weak, and the customer then needs a new code.

The session

Field	What it is
access_token	The customer's session token. Calls that act for the customer will take it.
token_type	`bearer`
expires_in	Seconds until the access token runs out.
expires_at	When it runs out, in Unix seconds.
refresh_token	Trade it for the next session with Refresh. It works once.
customer.id	The customer's id, the same in every session.
customer.email	The customer's email address.
customer.name	The name they registered with, or null.
customer.access	`granted`, or `pending` while your store approves new customers first. It becomes `granted` when an owner approves the customer under Customers in your Bench. Each refresh returns the current value.

Limits

register	10 a minute for your store.
login	5 a minute for one email address.
reset-password	10 a minute for your store, and 5 a minute for one email address.
reset-password/confirm	5 a minute for one email address.

Over a limit the answer is 429 rate_limit with a Retry-After header in seconds. Wait that long, then try again.

Errors

Answer	When
400 parameter_missing	A required parameter is missing. param names it.
400 parameter_unknown	A parameter the call doesn't take, often a typo. param names it.
400 parameter_invalid	A parameter isn't a string, or is too long.
400 email_invalid	The email address isn't valid.
400 password_too_weak	The password is too short.
409 email_exists	The email already has an account.
400 invalid_credentials	Wrong email or password.
400 refresh_token_invalid	The refresh token was used already, or its session ended.
400 code_invalid	The reset code is wrong, used or more than an hour old.
401 api_key_invalid	No key, or one Diamra doesn't know. See API keys.
401 api_key_revoked	The key was revoked in your console.
403 plan_required	Your store isn't on the Retail plan. Its keys work again once it is.
429 rate_limit	Too many calls in a minute.

An errorHTTP

HTTP/2 409
content-type: application/json
request-id: req_9d24c1e07b3a4f68

{
  "error": {
    "type": "invalid_request_error",
    "code": "email_exists",
    "message": "An account with this email already exists. Log the customer in instead.",
    "param": "email"
  }
}