Sign with RS-ID (Oauth2 style)

Sign in with RS-ID lets users log in to your website with their RS-ID mobile app, instead of a password. It follows the standard OAuth 2.0 Authorization Code flow.

Your site sends the user to the RS-ID auth page. The page shows a QR code; the user scans it with the RS-ID mobile app and confirms their identity with their face. RS-ID then sends the user back to your site with a one-time authorization code, and your backend exchanges that code for the user's verified profile.

You never handle passwords, passport data entry or face checks — RS-ID does it, and your backend gets a verified identity.

Use cases

Use case	Example
Passwordless login	Users sign in to your web portal by scanning a QR code with the RS-ID app.
Verified registration	A new user signs up in one step; your account is created with verified name, PINFL and document data.
Login for sensitive services	Banking, insurance, government or medical portals that need a real, verified person at every login.
Single identity across services	The same RS-ID identity is used to sign in to several of your products.

2. Terminology

Term	Who / what it is
Client	The company integrating RS-ID (you). Registered in RS-ID as an AUTH project and issued a `client_id` / `client_secret` and a registered `redirect_uri`. Includes the client frontend (your website) and the client backend.
User	The person signing in — your customer, who has the RS-ID mobile app.
RS-ID auth page	The RS-ID web page where the user scans the QR code.
RS-ID mobile app	The RS-ID app on the user's phone, used to scan the QR code and confirm identity.
Server	The RS-ID server that issues authorization codes and returns the user profile.
Authorization code (`code`)	A one-time code RS-ID sends to your `redirect_uri` after the user signs in. Valid for 5 minutes, usable once.
`redirect_uri`	The URL on your site where RS-ID sends the user back with the `code`. Must be registered in RS-ID.
`state`	A random value your site generates for each login and checks on return, to protect against CSRF.
PINFL	Personal identification number of an individual — 14 digits.

3. How it works

The user clicks Sign in with RS-ID on your site.

Your site redirects the user to the RS-ID auth page with client_id, redirect_uri, response_type=code and state (7.1).

The auth page shows a QR code that refreshes every 30 seconds (7.2).

The user scans the QR code with the RS-ID mobile app and confirms their identity.

The auth page redirects the user to your redirect_uri with code and state (7.3).

Your backend checks state and exchanges the code for the user's profile with POST /v1/user/by-code (7.4).

You sign the user in to your system.

4. Integration diagram

5. Environments

Environment	RS-ID auth page	API base URL
Stage (testing)	`https://auth.stage.rsid.uz`	`https://sdk.stage.rsid.uz/web/api`
Production	`https://auth.rsid.uz`	`https://sdk.rsid.uz/web/api`

Stage and production use different client_id / client_secret. The redirect_uri is registered separately for each environment.

6. General rules

Response envelope

Every API response has the same structure:

{ "data": { }, "code": 0, "message": "Success" }

Field	Type	Description
`code`	integer	`0` — success. Any other value is an error (see the error tables). Always check `code`, not only the HTTP status.
`message`	string	Human-readable text in the request language (uz / ru / en). Do not parse it.
`data`	any	Response payload. Absent on errors.

Security

client_secret stays on your backend. Never put it into the browser or a mobile app. Exchange the code only from your backend.

Always use and check state. Generate a new random state for each login, keep it in the user's session, and reject the return if it does not match.

The code is one-time and short-lived. Exchange it right away — it is valid for 5 minutes and can be used only once.

Use HTTPS for your redirect_uri.

7. API definitions

7.1 Redirect the user to the RS-ID auth page

Your site sends the user's browser to the RS-ID auth page.

Method - GET (browser redirect)
URL - {auth_page_url}/

Query parameters

Field	Type	Required	Length / format	Description
`client_id`	string	Yes	—	Your `client_id` issued by RS-ID.
`redirect_uri`	string	Yes	URL, URL-encoded	Where RS-ID sends the user back. Must exactly match the `redirect_uri` registered in RS-ID.
`response_type`	string	Yes	`code`	Always `code` (authorization code flow).
`state`	string	Recommended	Random string	Random value generated by your site for this login. Returned unchanged with the code.

Example

https://auth.rsid.uz/?client_id=shop-example-auth&redirect_uri=https%3A%2F%2Fshop.example.uz%2Fauth%2Frsid%2Fcallback&response_type=code&state=Zx81kQ2mP0

7.2 User flow on the RS-ID auth page

The auth page shows a QR code. For security, the QR code is regenerated every 30 seconds — an old QR code cannot be used.

The user opens the RS-ID mobile app and scans the QR code.

The user confirms their identity in the app (face check).

When identification succeeds, the auth page redirects the user back to your site (7.3).

If the user closes the page or does not scan in time, nothing is sent to your site; the user can start again from 7.1.

7.3 Redirect back to your site with the code

After a successful sign-in, the RS-ID auth page redirects the user's browser to your redirect_uri:

https://shop.example.uz/auth/rsid/callback?code=Zx81kQ2mP0aB7cD9eF1gH3&state=Zx81kQ2mP0

Parameter	Description
`code`	One-time authorization code. Valid for 5 minutes, usable once.
`state`	The value you sent in 7.1. Compare it with the one saved in the user's session; if it differs, stop the login.

Your callback page passes code (and state) to your backend, which calls 7.4.

7.4 Get user info by code

The client backend exchanges the authorization code for the user's verified profile.

Method - POST
Endpoint - {base_url}/v1/user/by-code — no Authorization header
Content-Type (Headers) - application/json

Request body

Field	Type	Required	Length / format	Description
`client_id`	string	Yes	Non-empty	Your `client_id` (AUTH project).
`client_secret`	string	Yes	Non-empty	Your `client_secret`.
`code`	string	Yes	Non-empty	The `code` from 7.3.
`grant_type`	string	Yes	`authorization_code`	Always `authorization_code`.

{
  "client_id": "shop-example-auth",
  "client_secret": "s3cr3t-value",
  "code": "Zx81kQ2mP0aB7cD9eF1gH3",
  "grant_type": "authorization_code"
}

Response

Field	Type	Description
`data.user_info.first_name`	string	First name.
`data.user_info.last_name`	string	Last name.
`data.user_info.middle_name`	string	Patronymic. `-` if the person has none.
`data.user_info.pinfl`	string	PINFL, 14 digits. Use it as the stable user identifier.
`data.user_info.gender`	string	Gender.
`data.user_info.birth_date`	string	`yyyy-MM-dd`.
`data.user_info.birth_place`	string	Place of birth.
`data.document_info.document`	string	Document series and number.
`data.document_info.type`	string	Document type.
`data.document_info.issued_by`	string	Issuing authority.
`data.document_info.issued_at`	string	Issue date, `yyyy-MM-dd`.
`data.document_info.expiry_at`	string	Expiry date, `yyyy-MM-dd`.
`data.contact_info.phone`	string	Phone number from the RS-ID account.
`data.contact_info.email`	string	Email from the RS-ID account, if set.
`data.permanent_address`	object	Not returned in this flow (`null`).
`data.temporary_address`	object	Not returned in this flow (`null`).
`code`	integer	`0` on success.
`message`	string	Result text.

{
  "data": {
    "user_info": {
      "first_name": "ALISHER",
      "last_name": "KARIMOV",
      "middle_name": "BAXTIYOROVICH",
      "pinfl": "12345678901234",
      "gender": "MALE",
      "birth_date": "1990-01-01",
      "birth_place": "TOSHKENT",
      "birth_country": null,
      "nationality": null,
      "citizenship": null
    },
    "document_info": {
      "document": "AA1234567",
      "type": "PASSPORT",
      "issued_by": "IIV 26283",
      "issued_at": "2018-05-10",
      "expiry_at": "2028-05-09"
    },
    "contact_info": {
      "phone": "998901234567",
      "email": "alisher.karimov@example.uz"
    },
    "permanent_address": null,
    "temporary_address": null
  },
  "code": 0,
  "message": "Success"
}

Errors

Code	Reason
`-1083`	`client_id` not found.
`-1002`	The client is not an AUTH project.
`-1089`	`grant_type` is not `authorization_code`.
`-1018`	`code` is invalid, expired (older than 5 minutes) or already used, or `client_secret` is wrong. Start the login again from 7.1.
`-1035`	`code` is not linked to a sign-in. Start the login again from 7.1.
`400`	A required field is empty.

8. Error codes

Code	Name	Meaning
`0`	SUCCESS	Success.
`-9`	SYSTEM_ERROR	Unexpected server error.
`-1002`	CLIENT_NOT_PERMITTED	The client is not an AUTH project.
`-1018`	USER_NOT_FOUND	Code invalid, expired or already used, or wrong credentials.
`-1035`	INVALID_QR_TOKEN	Code is not linked to a sign-in.
`-1083`	CLIENT_PROJECT_NOT_FOUND	`client_id` not found.
`-1089`	INVALID_GRAND_TYPE	`grant_type` is not `authorization_code`.

Sign with RS-ID (Oauth2 style)

1. What is Sign in with RS-ID#

Use cases#

2. Terminology#

3. How it works#

4. Integration diagram#

5. Environments#

6. General rules#

Response envelope#

Security#

7. API definitions#

7.1 Redirect the user to the RS-ID auth page#

7.2 User flow on the RS-ID auth page#

7.3 Redirect back to your site with the code#

7.4 Get user info by code#

8. Error codes#

1. What is Sign in with RS-ID