> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/service/verify-a-users-pin-and-sign-them-in.md).

# Verify a user's PIN and sign them in

Check a user's PIN server-side and sign them in. This is what the lock screen on a shared service device calls: the app locks between users, and each person unlocks it with their own user id and PIN rather than working as the screen account, the login the screen itself is signed in with. A correct PIN answers AccountLoginResponse: accessToken, the unlock token — an access token for the user in the path — and tenantUser, that user's record. The unlock token is the platform's own access token, with the same lifetime as the access token post-account issues, and the client sends it as the bearer on everything that follows while the screen is unlocked. The caller of each of those requests is the person the platform authenticated by PIN: every request is judged on their permissions, and every write is attributed to them and recorded in the audit entries under their name — never under a uid a client chose to send. The unlock token also carries the screen account — the login the screen is signed in with — and the time of the unlock. The screen account is the login this operation is called under, except under an unlock token, when the screen passes from one person to the next: the new unlock token then carries the screen account of the old one, not the person it was issued for. The unlock time is the time of this verification. Every event written under the unlock token records the screen account as screenAccountTenantUserUid, so the timeline says which screen account the work was done under as well as who did it. The unlock token is refreshed through post-tenants-account, which answers a fresh one carrying the same screen account and the same unlock time. An unlock token already issued works until it expires, unless the user can no longer log in, which every operation refuses at once; the refresh is refused with a 401 once the unlock is older than 12 hours or while the user's PIN is locked (pinLocked), and the person then unlocks again with their PIN. Failed attempts are counted server-side on the tenant user, for every tenant. The first four consecutive failures against one user cost nothing. From the fifth on, every second failure starts a wait before the next attempt against that user is judged — 10 seconds after the fifth, 30 seconds after the seventh, 1 minute after the ninth, 5 minutes after the eleventh, 10 minutes after the thirteenth and 30 minutes after the fifteenth, the failure between each pair costing nothing — and the seventeenth locks the user until someone holding TENANT\_USER gives them a new PIN through the tenant user update. An attempt made while a wait is running or a lock is set is refused exactly as a wrong PIN, is not counted and does not extend the wait. A correct PIN of a user who can log in resets the count of the user in the path; the seventeenth failure in a row against a user locks them. A count with no failure for 24 hours starts again from nothing on the next attempt; a lock is never lifted by time. Every attempt that does not succeed and is not refused for a running wait or a lock counts as a failure against the user in the path — a wrong PIN, an empty PIN, and a user who cannot log in whatever PIN is sent, alike; an attempt against a uid that names nobody is refused and counts nowhere, and its answer is the same 401. A user has one ladder across every operation that takes their PIN — this one, the secret reveal, the cash reconciliation review, post-account and post-device-link: a failure on any of them counts on it, a wait or a lock set through any of them refuses all of them, and a correct PIN of a user who can log in, on any of them, resets it. The answer never says whether the user exists or is locked: a wrong PIN, an unknown user, a user who cannot log in, an empty PIN, a running wait and a lock are all the same 401 with the same body, so the answer to an attempt cannot be used to tell which uids belong to the tenant's staff. Blocking a user's access to the tenant deactivates them, so a blocked user is one who cannot log in. The state of the ladder is read on the user record instead, which every member of the tenant can list, among the account types their own account type lets them see: pinLockedUntil says when a running wait ends and pinLocked that the user is locked, which is how a client shows a countdown or sends the person to a tenant administrator. A new PIN set through the tenant user update, which TENANT\_USER guards, clears it; a user setting their own PIN through the tenant account update does not. The PIN is never returned anywhere in the API. It is not open to an integration token: an integration account is not a screen anyone unlocks.

Required permissions: SERVICE\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Service","description":"Service"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"}},"responses":{"AccountLoginResponse":{"content":{"application/json":{"schema":{"properties":{"accessToken":{"type":"string"},"tenantUser":{"$ref":"#/components/schemas/TenantUserResponseSchema"}},"required":["accessToken","tenantUser"],"type":"object"}}},"description":"Example response"}},"schemas":{"TenantUserResponseSchema":{"title":"TenantUserResponseSchema","type":"object","required":["accountType","createdAt","displayName","email","externalId","firstname","lastAccessed","lastModifiedAt","lastname","mobile","pinLocked","pinLockedUntil","status","storeAccess","tenantUid","tenantName","tenantRole","tenantUserUid","userCode","languageCode","permissions"],"properties":{"accountType":{"$ref":"#/components/schemas/TenantAccountTypeENUM"},"createdAt":{"format":"date-time","type":"string"},"defaultStoreUid":{"$ref":"#/components/schemas/OptionalUID"},"displayName":{"type":"string"},"email":{"$ref":"#/components/schemas/EmailTYPE"},"externalId":{"type":"string"},"firstname":{"type":"string"},"lastAccessed":{"format":"date-time","type":"string"},"lastModifiedAt":{"format":"date-time","type":"string"},"lastname":{"type":"string"},"mobile":{"type":"string"},"pinLocked":{"type":"boolean","description":"The user's PIN is locked after repeated failures, until someone holding TENANT_USER gives the user a new PIN through the tenant user update. While it is set no PIN of theirs is accepted — not by the tenant user verify-pin operation, the secret reveal, the cash reconciliation review, the device login or the device link — and no unlock token of theirs is refreshed. The ladder that leads here is described on the verify-pin operation."},"pinLockedUntil":{"type":"string","format":"date-time","nullable":true,"description":"When the running wait on the user's PIN ends, after repeated failures; until then every PIN attempt against the user is refused. null when no wait is running. A locked user reads null here and pinLocked true."},"status":{"$ref":"#/components/schemas/TenantUserStatusENUM"},"storeAccess":{"type":"array","items":{"$ref":"#/components/schemas/UserStoreAccessResponseSchema"}},"tenantUid":{"$ref":"#/components/schemas/UID"},"tenantName":{"type":"string"},"tenantRole":{"$ref":"#/components/schemas/TenantRoleENUM"},"tenantUserUid":{"$ref":"#/components/schemas/UID"},"userCode":{"type":"string"},"languageCode":{"$ref":"#/components/schemas/LanguageCode"},"permissions":{"$ref":"#/components/schemas/TenantUserPermissionResponseSchema"}},"description":""},"TenantAccountTypeENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| FULL | Access to backoffice and onboarding of new devices|\n| REGULAR | Can only login to already onboarded devices|\n| SUPPORT | Support account|\n| INTEGRATION | Computer integration account|","enum":["FULL","REGULAR","SUPPORT","INTEGRATION"],"title":"TenantAccountTypeENUM","type":"string"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"EmailTYPE":{"title":"Email","type":"string"},"TenantUserStatusENUM":{"title":"TenantUserStatusENUM","enum":["PENDING_INVITE","ACTIVE","INACTIVE"],"type":"string"},"UserStoreAccessResponseSchema":{"title":"UserStoreAccessResponseSchema","type":"object","required":["createdAt","lastModifiedAt","storeAccessUid","storeUid","storeRole"],"properties":{"createdAt":{"format":"date-time","type":"string"},"lastModifiedAt":{"format":"date-time","type":"string"},"storeAccessUid":{"$ref":"#/components/schemas/UID"},"storeUid":{"$ref":"#/components/schemas/UID"},"storeRole":{"$ref":"#/components/schemas/StoreRoleENUM"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"StoreRoleENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| ADMIN | Store admin.|\n| BACKOFFICE | Access to all backoffice functionality (price changes, purhcase order, etc)|\n| REGULAR | Access to app funtionality (product lookup, create sales, delivery)|","enum":["ADMIN","BACKOFFICE","REGULAR"],"title":"StoreRoleENUM","type":"string"},"TenantRoleENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n| BLOCKED | Blocked from this tenant|\n| ACCESS | Only access to the tenant.|\n| ADMIN | Tenant admin, allow full access to tenant and can add users and new stores.|\n| BACKOFFICE | Access to product, pricelists, etc.|","enum":["ACCESS","ADMIN","BACKOFFICE","BLOCKED"],"title":"TenantRoleENUM","type":"string"},"LanguageCode":{"title":"LanguageCode","description":"Lowercase two-letter ISO 639-1 language code, like nb, en or sv.","type":"string"},"TenantUserPermissionResponseSchema":{"title":"TenantUserPermissionResponseSchema","type":"object","required":["tenant","stores","organizations"],"properties":{"tenant":{"type":"array","items":{"type":"string"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/StorePermissionResponseSchema"}},"organizations":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationPermissionResponseSchema"}}}},"StorePermissionResponseSchema":{"title":"StorePermissionResponseSchema","type":"object","required":["store","permissions"],"properties":{"store":{"$ref":"#/components/schemas/BasicStoreResponseSchema"},"permissions":{"type":"array","items":{"type":"string"}}}},"BasicStoreResponseSchema":{"title":"BasicStoreResponseSchema","type":"object","required":["name","storeUid","organizationUid","organizationName"],"properties":{"name":{"type":"string"},"storeUid":{"$ref":"#/components/schemas/UID"},"organizationUid":{"$ref":"#/components/schemas/UID"},"organizationName":{"type":"string"}}},"OrganizationPermissionResponseSchema":{"title":"OrganizationPermissionResponseSchema","type":"object","required":["organization","permissions"],"properties":{"organization":{"$ref":"#/components/schemas/BasicOrganizationResponseSchema"},"permissions":{"type":"array","items":{"type":"string"}}}},"BasicOrganizationResponseSchema":{"title":"BasicOrganizationResponseSchema","type":"object","required":["name","organizationUid"],"properties":{"name":{"type":"string"},"organizationUid":{"$ref":"#/components/schemas/UID"}}},"TenantUserVerifyPinRequestSchema":{"title":"TenantUserVerifyPinRequestSchema","description":"The PIN of the user in the path, sent to be checked. It is the whole body: nothing else is needed to establish that the person at the device is who they say they are.\nThe PIN is compared server-side and never returned by any operation. It is the same PIN as the password the device login and the device link take, and the one the secret reveal verifies again.","type":"object","required":["pin"],"properties":{"pin":{"type":"string","writeOnly":true,"description":"The PIN the user unlocks with. It is compared server-side and never echoed back."}}}},"requestBodies":{"TenantUserVerifyPinRequest":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantUserVerifyPinRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/users/{tenantUserUid}/verifypin":{"post":{"summary":"Verify a user's PIN and sign them in","operationId":"post-tenants-users-verifypin","description":"Check a user's PIN server-side and sign them in. This is what the lock screen on a shared service device calls: the app locks between users, and each person unlocks it with their own user id and PIN rather than working as the screen account, the login the screen itself is signed in with.\nA correct PIN answers AccountLoginResponse: accessToken, the unlock token — an access token for the user in the path — and tenantUser, that user's record. The unlock token is the platform's own access token, with the same lifetime as the access token post-account issues, and the client sends it as the bearer on everything that follows while the screen is unlocked. The caller of each of those requests is the person the platform authenticated by PIN: every request is judged on their permissions, and every write is attributed to them and recorded in the audit entries under their name — never under a uid a client chose to send.\nThe unlock token also carries the screen account — the login the screen is signed in with — and the time of the unlock. The screen account is the login this operation is called under, except under an unlock token, when the screen passes from one person to the next: the new unlock token then carries the screen account of the old one, not the person it was issued for. The unlock time is the time of this verification. Every event written under the unlock token records the screen account as screenAccountTenantUserUid, so the timeline says which screen account the work was done under as well as who did it.\nThe unlock token is refreshed through post-tenants-account, which answers a fresh one carrying the same screen account and the same unlock time. An unlock token already issued works until it expires, unless the user can no longer log in, which every operation refuses at once; the refresh is refused with a 401 once the unlock is older than 12 hours or while the user's PIN is locked (pinLocked), and the person then unlocks again with their PIN.\nFailed attempts are counted server-side on the tenant user, for every tenant. The first four consecutive failures against one user cost nothing. From the fifth on, every second failure starts a wait before the next attempt against that user is judged — 10 seconds after the fifth, 30 seconds after the seventh, 1 minute after the ninth, 5 minutes after the eleventh, 10 minutes after the thirteenth and 30 minutes after the fifteenth, the failure between each pair costing nothing — and the seventeenth locks the user until someone holding TENANT_USER gives them a new PIN through the tenant user update. An attempt made while a wait is running or a lock is set is refused exactly as a wrong PIN, is not counted and does not extend the wait. A correct PIN of a user who can log in resets the count of the user in the path; the seventeenth failure in a row against a user locks them. A count with no failure for 24 hours starts again from nothing on the next attempt; a lock is never lifted by time. Every attempt that does not succeed and is not refused for a running wait or a lock counts as a failure against the user in the path — a wrong PIN, an empty PIN, and a user who cannot log in whatever PIN is sent, alike; an attempt against a uid that names nobody is refused and counts nowhere, and its answer is the same 401. A user has one ladder across every operation that takes their PIN — this one, the secret reveal, the cash reconciliation review, post-account and post-device-link: a failure on any of them counts on it, a wait or a lock set through any of them refuses all of them, and a correct PIN of a user who can log in, on any of them, resets it.\nThe answer never says whether the user exists or is locked: a wrong PIN, an unknown user, a user who cannot log in, an empty PIN, a running wait and a lock are all the same 401 with the same body, so the answer to an attempt cannot be used to tell which uids belong to the tenant's staff. Blocking a user's access to the tenant deactivates them, so a blocked user is one who cannot log in. The state of the ladder is read on the user record instead, which every member of the tenant can list, among the account types their own account type lets them see: pinLockedUntil says when a running wait ends and pinLocked that the user is locked, which is how a client shows a countdown or sends the person to a tenant administrator. A new PIN set through the tenant user update, which TENANT_USER guards, clears it; a user setting their own PIN through the tenant account update does not.\nThe PIN is never returned anywhere in the API.\nIt is not open to an integration token: an integration account is not a screen anyone unlocks.\n\nRequired permissions: SERVICE_ORDER","responses":{"200":{"$ref":"#/components/responses/AccountLoginResponse"},"401":{"description":"The PIN was refused: a wrong PIN, an unknown user, a user who cannot log in, an empty PIN, a running wait and a lock all answer this, alike. No token is issued."}},"requestBody":{"$ref":"#/components/requestBodies/TenantUserVerifyPinRequest"},"tags":["Service"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/service/verify-a-users-pin-and-sign-them-in.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
