public-api-docs

User API Account And Authentication Guide

Overview

Account and authentication endpoints support user registration, sign-in bootstrap flows, profile management, password reset, phone/email verification, terms acceptance, localized messages, and account deletion. Use these endpoints when building user onboarding, profile screens, compliance gates, and self-service account flows.

Related reference: User API Authentication API User API Guide Authentication Error Codes

Core Concepts

Access Tokens

The Authentication API issues and refreshes access tokens. The User API then uses the access token to identify the current user for profile, rental, booking, payment, invoice, group, and benefit operations.

Signed Bootstrap Requests

Some unauthenticated account bootstrap endpoints accept signature and timestamp query parameters. These protect sign-up, sign-in, OTP resend, and password reset flows from unauthorized use. Generate signatures as described in API Suite Documentation.

One-Time Codes

Phone-number and email-code sign-in are two-step flows. The customer bootstrap endpoint sends the one-time code and returns 204 No Content. The app then confirms the code through the Authentication API sign-in endpoint. Successful confirmation returns the access token and refresh token.

Do not confuse this with phone verification for an already signed-in user. POST /customers/verify/send and POST /customers/verify/check/{code} verify the phone number on the current user’s profile; they do not return login tokens.

Current User

GET /customers returns the profile of the authenticated user. PATCH /customers updates the same current-user profile. User-facing applications should treat these endpoints as self-service endpoints, not as generic customer administration.

Terms And Conditions

Terms are branch-, vehicle-, and sometimes version-specific. A user can be blocked from starting a rental or booking until the relevant T&C are accepted. Fetch the required terms, display them to the user, then accept them through the User API.

Common User Workflows

Sign In And Refresh Tokens

Use the Authentication API for token lifecycle:

Task Endpoint
Sign in with email/password POST /sign-in-email
Sign in with phone number POST /sign-in-phone-number
Sign in with email code POST /sign-in-email-code
Sign in with Gaiyo POST /sign-in-gaiyo
Social login POST /social-login
API-client sign-in POST /sign-in-api-client
Refresh access token POST /refresh-token
Logout POST /logout
Exchange OpenID token POST /user/openid-token-exchange

Two-factor authentication endpoints are also part of the Authentication API:

Task Endpoint
Get 2FA secret POST /user/2fa-secret
Get 2FA QR code POST /user/2fa-qr-code
Enable 2FA POST /user/2fa-enable
Validate 2FA code POST /user/2fa-code-validate

Register Or Bootstrap A User

Use customer endpoints for sign-up and verification-code bootstrap flows:

Task Endpoint
Create user account POST /customers
Create or sign in with phone number POST /customers/create-or-sign-in-with-phone-number
Create or sign in with email code POST /customers/create-or-sign-in-with-email-code
Social sign-up POST /customers/social-sign-up

Send Accept-Language where required so the account, messages, and communication flows use the intended locale.

Confirm A Phone Or Email Code

For phone-number sign-in or email-code sign-in, split the flow into a code request and a code confirmation.

Phone-number flow:

  1. Resolve the user’s branch, usually with GET /branches/resolve or a known branch selection.
  2. Generate the request signature from the signature key, timestamp, phone number, and signature key.
  3. Call POST /customers/create-or-sign-in-with-phone-number?signature={signature}&timestamp={timestamp} with phoneNumber, branchId, optional language, optional oneSignalDeviceId, and optional tncAccepted.
  4. The API returns 204 No Content and sends an SMS code to the phone number.
  5. Ask the user to enter the received code.
  6. Call POST /sign-in-phone-number in the Authentication API with phoneNumber and code.
  7. Store the returned accessToken and refreshToken. If the response says MFA is required, complete the 2FA flow before treating the user as fully signed in.
  8. Call GET /customers to load the current profile and continue onboarding checks.

Email-code flow:

  1. Generate the request signature from the signature key, timestamp, email address, and signature key.
  2. Call POST /customers/create-or-sign-in-with-email-code?signature={signature}&timestamp={timestamp} with email, branchId, optional language, and optional tncAccepted.
  3. The API returns 204 No Content and sends an email code.
  4. Ask the user to enter the received code.
  5. Call POST /sign-in-email-code in the Authentication API with email and code.
  6. Store the returned tokens and load GET /customers.

The bootstrap endpoint is intentionally not the confirmation endpoint. It creates the user if needed, or starts sign-in for an existing user, and sends the code. The Authentication API endpoint confirms the code and returns tokens.

Common implementation mistakes:

Mistake Correct behavior
Expecting POST /customers/create-or-sign-in-with-phone-number to return tokens It returns 204; confirm with POST /sign-in-phone-number.
Sending the code to POST /customers/verify/check/{code} after sign-in bootstrap Use POST /sign-in-phone-number or POST /sign-in-email-code for login-code confirmation.
Reusing an old signature Generate a fresh signature and timestamp for each signed bootstrap request.
Ignoring mfaRequired in the sign-in response Complete the 2FA validation flow when required.

Manage The Current Profile

Task Endpoint
Get current user profile GET /customers
Update current user profile PATCH /customers
Get signed current-user data GET /customers/signed
Request account deletion POST /customers/request-deletion

Use GET /customers/signed when a trusted downstream system needs the current user’s profile data as a signed JWT for verification.

Password And Verification Flows

Task Endpoint
Request password reset POST /customers/reset/{email}
Set password with reset code POST /set-password/{code}
Send phone verification code POST /customers/verify/send
Check phone verification code POST /customers/verify/check/{code}
Resend email verification POST /customers/verify-email/resend/{email}
Initialize external verification session POST /verification/init

Verification state can affect rental requirements. If a rental start fails because verification is missing or pending, route the user to the relevant verification flow rather than retrying the rental request.

Use the phone verification endpoints only after the user is authenticated:

  1. The signed-in user adds or has a phone number on their profile.
  2. Call POST /customers/verify/send.
  3. The user receives an SMS code.
  4. Call POST /customers/verify/check/{code}.
  5. The API returns 204 No Content; re-fetch GET /customers to see the updated verification state.

Identity Cards

Use GET /customer-identity-cards to list identity cards assigned to the current user. These are user-facing credentials for tenants that support customer identity-card workflows.

Show identity cards in profile or account screens only when the response contains cards. Do not build card administration with the User API; operator-side card creation, assignment, and lifecycle management belong to the Operations API.

Terms And Conditions

Task Endpoint
List matching T&C GET /termsandconditions
Get one T&C GET /termsandconditions/{id}
Accept T&C POST /termsandconditions
List current user’s accepted T&C for a branch GET /customers/termsandconditions

T&C can be requested by branch or vehicle context. Always display the exact terms returned by the API and store acceptance through POST /termsandconditions.

Most Relevant APIs

Area Endpoints
Authentication POST /sign-in-email, POST /sign-in-phone-number, POST /sign-in-email-code, POST /sign-in-gaiyo, POST /social-login, POST /sign-in-api-client, POST /refresh-token, POST /logout
2FA and OpenID POST /user/2fa-secret, POST /user/2fa-qr-code, POST /user/2fa-enable, POST /user/2fa-code-validate, POST /user/openid-token-exchange
Account GET /customers, POST /customers, PATCH /customers, GET /customers/signed, POST /customers/request-deletion
Account bootstrap POST /customers/create-or-sign-in-with-phone-number, POST /customers/create-or-sign-in-with-email-code, POST /customers/social-sign-up
Verification POST /customers/verify/send, POST /customers/verify/check/{code}, POST /customers/verify-email/resend/{email}, POST /verification/init
Identity cards GET /customer-identity-cards
Password POST /customers/reset/{email}, POST /set-password/{code}
Terms GET /termsandconditions, GET /termsandconditions/{id}, POST /termsandconditions, GET /customers/termsandconditions

Implementation Notes