IZI API Authentication & Tokens
Bu içerik henüz dilinizde mevcut değil.
IZI API Authentication & Tokens
Section titled “IZI API Authentication & Tokens”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.
Step 1 — Get a Token
Section titled “Step 1 — Get a Token”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):
| Code | When |
|---|---|
NotFound | No user with this email |
InvalidCredentials | Wrong password, or no password set |
UnverifiedEmail | Email not verified |
SignUpRequired | Sign-up not completed |
TooManyAttempts | The 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:
checkEmail(email)— whether the user exists and may sign in with a password.sendEmailOtp(email, countryCode)— send the code to the email.verifyEmailOtp(email, code, countryCode)— check the code; the response has the sameaccessTokenanduserasloginWithEmailPassword.
All three mutations are available without a token.
Step 2 — Use the Token
Section titled “Step 2 — Use the Token”Pass accessToken in the header of every request:
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.
Token for One Club
Section titled “Token for One Club”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.
Roles and Permissions
Section titled “Roles and Permissions”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.
| Role | Type | Access |
|---|---|---|
| Owner | Org ownership | Full access to all organization clubs; not an assignable staff role |
ADMINISTRATOR (Administrator) | Built-in staff role | Base club-level permissions within assigned clubs |
| Custom roles (e.g. Manager, Cashier) | Created by the owner | Exactly 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.
Related Pages
Section titled “Related Pages”- IZI API: Overview — per-contour addresses and anonymous access
- API Error Codes — error format and common codes
- SDK Examples — ready wrappers in JS and Python
Sık sorulan sorular
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.
IZI LLC (ООО «ИЗИ»), TIN 7842227686, OGRN 1257800012249, office 1, premises 3-N, lit. A, 15-17 Perekupnoy lane, Saint Petersburg, 191024, Russia, admin@izi.is · Cookie settings