Ir al contenido

IZI API Authentication & Tokens

Опубликовано: · Обновлено: (1 месяц назад)· IZI Team

Esta página aún no está disponible en tu idioma.

IZI API uses JWT (JSON Web Token). A club employee signs in by email and receives an accessToken — a token with the CRM role. There is one token: no separate refresh token exists, so after it expires you sign in again.

mutation Login(
$email: EmailAddress!
$password: String!
$countryCode: CountryCode!
) {
loginWithEmailPassword(
email: $email
password: $password
countryCode: $countryCode
) {
accessToken
user {
id
email
name
}
}
}
{
"email": "partner@example.com",
"password": "your_password",
"countryCode": "RU"
}

countryCode is required: it is a two-letter country code and is written into the token.

Response:

{
"data": {
"loginWithEmailPassword": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "4f1c2d6e-...",
"email": "partner@example.com",
"name": "John"
}
}
}
}

Besides accessToken and user, the response has a suggestPasswordSetup flag — a hint for the CRM interface to offer the user to set a password.

Possible login errors (errors[].extensions.code):

CodeWhen
NotFoundNo user with this email
InvalidCredentialsWrong password, or no password set
UnverifiedEmailEmail not verified
SignUpRequiredSign-up not completed
TooManyAttemptsThe failed sign-in budget is exhausted — see below

The sign-in budget is counted per email + IP address pair: five failed attempts pass within a single hour window, and the sixth answers TooManyAttempts. The window is fixed and aligned to the clock, not to your first attempt: the counter resets on the hour boundary, so waiting an hour from the refusal is neither necessary nor always sufficient. The API deliberately does not disclose how long the block lasts — this error carries no retryAfter field.

Not every refusal spends the budget: a wrong password and an unknown email (NotFound) consume an attempt, while UnverifiedEmail and “no password set” do not. A successful sign-in returns only its own attempt; earlier failures in the same window stay counted. The budget applies to password sign-in specifically — signing in with an email code has its own limits on sending and on the number of code entries.

Signing in without a password — with an email code

Section titled “Signing in without a password — with an email code”

If no password is set or it is forgotten, a token is issued for a one-time code:

  1. checkEmail(email) — whether the user exists and may sign in with a password.
  2. sendEmailOtp(email, countryCode) — send the code to the email.
  3. verifyEmailOtp(email, code, countryCode) — check the code; the response has the same accessToken and user as loginWithEmailPassword.

All three mutations are available without a token.

Pass accessToken in the header of every request:

Terminal window
curl -X POST https://api.x.izi.is/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-d '{"query": "query MyProfile { userProfile { id email name } }"}'

The API address depends on the club’s contour — see IZI API: Overview.

In code, configure the HTTP client once:

const client = new GraphQLClient("https://api.x.izi.is/graphql", {
headers: {
Authorization: `Bearer ${accessToken}`,
},
});

If the token has expired or is damaged, the request runs as anonymous: open fields answer as usual, protected fields return an Unauthorized error.

To avoid learning about expiry from the first refused operation, ask the API about the token itself — the crmTokenContext query returns the userId, email, clubId and expiresAt of the credential the request arrived with:

query MyTokenContext {
crmTokenContext {
userId
email
clubId
expiresAt
}
}

The CRM token’s lifetime is a per-contour setting, not an API constant: there is no single number that holds for every contour. Take expiresAt, or the exp field of the JWT itself, rather than a value hard-coded in your client.

exchangeClubToken(clubId) issues, from the current CRM token, a new one restricted to one club and valid for at most an hour. Its rights are never wider than the original token’s.

Another mutation, exchangeRegionToken(countryCode), reissues a token for a different contour, and it must be called against the target contour’s address, not your own: with a still-valid token from the contour you came from, it finds the account with the same email in the target contour’s database and issues a local token. If no such account exists there, the answer is NotFound. The mutation is available to IZI support only.

The token does not carry the staff role: it holds only the credential kind (CRM), the user’s id and email, the country code and — for a club token — clubId. Permissions are read from the database on every request, so changing a role or a permission set takes effect on the next request, with no re-login.

IZI has one built-in staff role — Administrator — plus custom roles the organization owner creates.

RoleTypeAccess
OwnerOrg ownershipFull access to all organization clubs; not an assignable staff role
ADMINISTRATOR (Administrator)Built-in staff roleBase club-level permissions within assigned clubs
Custom roles (e.g. Manager, Cashier)Created by the ownerExactly the permissions the owner selects

Custom roles are defined in IZI CRM: the owner names the role freely and selects a permission set (clubPermissions / orgPermissions). “Manager” and “Cashier” are common examples — but they are not preset tiers. The owner creates them with whatever name and permission scope fits the operation.

For server-side integrations, create a dedicated user with a custom role scoped to the minimum permissions required. Don’t use the owner’s personal account.

Preguntas frecuentes

Can I get an API key or a service account?

No. IZI has no separate API keys or service accounts: a CRM token is always issued to a specific employee, and the rights are the rights of that employee's role at the time of the request, because permissions are read from the database on every request rather than written into the token.

How do I refresh an expired token?

There is no token refresh mutation. Once the token has expired, protected fields return an Unauthorized error — sign in again. The token lifetime is a per-contour setting, with no single number for all contours: to avoid waiting for the first error, read crmTokenContext.expiresAt or the exp field of the JWT itself.

About IZI