Use the Auth API when your app needs customer identity, session handling, or account-owned shopper state. It covers registration, login, refresh, password recovery, email verification, saved carts, wishlists, and account-context reads such as customer-group pricing.

Use the reference and OpenAPI spec for exact methods, paths, parameters, request bodies, token response shapes, and error responses.

• API track: Auth API.
• API version: latest.
• Spec: OpenAPI.
• Reference route: /reference/auth.
• OpenAPI: /reference/openapi/auth-api.
• Playground: /apis/auth/playground.

Use this API for

• Registering customers and issuing login credentials.
• Refreshing a signed-in session.
• Recovering passwords and verifying email addresses.
• Reading or changing the current user's profile.
• Saving cart references and managing wishlists.
• Resolving account-scoped organisation, order, customer-group, attribute, and file operations that the Auth API reference marks as Auth-owned.

Use the Shopper API for public catalog reads. Use the Management API for trusted administrative workflows that manage merchant-owned data.

Pick the right credential

Every Auth request is scoped by the app_id in the route. The credential then depends on the route group:

Core identity routes under /auth/... require the app api-key service token before they issue, refresh, or consume user credentials. Routes that act as the signed-in customer use the access token returned by login or refresh in the Authorization: Bearer \{access_token\} header.

Auth has three credential shapes. Do not infer the required credential from the Auth family name alone. Choose by route group and confirm the operation page before shipping:

• App-scoped server work: send api-key: \{service_token\} for /auth/*, /lookup/*, /attributes, /files, /shared/wishlists/\{token\}, and POST /organisations.
• Signed-in customer work: send Authorization: Bearer \{access_token\} for /user, /users/*, and /orders/*.
• Combined app and customer work: send both headers for non-create /organisations/*, /carts, /wishlists, and /customer-groups/*.

Confirm the operation page before shipping. Route families share a product surface, but they do not all share one credential model.

Some account-state routes require both headers because the server needs app authority and customer authority before the handler runs. For combined-header workflows, keep the service token in your backend and attach the customer's bearer credential only for the current request. Access-token middleware rejects tokens whose app does not match the route app.

Identity lifecycle

Signup creates an active user by default. When the request supplies pending, the user is created in pending state instead. The create flow validates the email, normalizes a supplied language value, applies the current password policy, rejects duplicates, stores a hashed password, and publishes a user-created event after a successful create.

Login checks the user by app and email. It only issues credentials when the email is verified, the user status is active, and the password matches. The response includes the user plus bearer credentials.

Credential creation stores a new refresh-token record and removes older refresh tokens for that user. Refresh calls validate the submitted refresh value, find the stored record, reject expired or unknown records, re-check that the user is verified and active, and return a new access credential pair. Use the latest values returned by the API after each refresh.

Password reset starts by creating a reset link for an existing verified user and publishing the reset-password event used by the delivery system. Changing a password requires the reset token, rejects missing or expired links, applies the password policy, stores the new hash, deletes the used link, and cleans up expired records.

Email verification starts by creating a verification link for an existing unverified user and publishes the verification event. Confirming the email rejects missing, expired, or already-used links; successful verification marks the user as verified, deletes the link, and publishes an account-confirmed event.

Base path shape

Auth API routes are scoped to an app.

https://customers.enad.io/api/v1/{app_id}/auth

When an operation path shows a colon-prefixed variable such as :app_id, treat it as a path variable and replace it with the real app value before making requests.

Main areas

Auth-owned areas include Organisations, Wishlist, Users, Auth, Attributes, Orders, Cart, Files, and Customer Groups. Use each operation page to confirm ownership before treating a route as account-scoped behavior.

Authentication model

Most Auth integrations use one of these headers. The operation page decides which one belongs on a given request:

api-key: {service_token}
Authorization: Bearer {access_token}

• Use api-key for app-scoped server work such as signup, login, lookup, attribute, file, and shared-wishlist routes.
• Use Authorization for current-user, user-by-ID, and customer-order reads.
• Send both headers for organisation account work, saved carts, wishlists, and customer-group price reads.
• Keep public catalog discovery in Shopper or Search; Auth responses can include account-specific state.

Do not put the app service token in browser code. Treat it as a server-side credential. Bearer values represent the current customer session and should stay bound to that app and user.

Common integration flow

1. Start with the Auth reference index for identity operations.
2. Confirm request and response shapes in the operation page.
3. Test the flow in the Auth API playground with development users.
4. Store tokens according to your application's platform and security model.
5. Refresh tokens using the refresh-token contract before access-token expiry.
6. Use the cart or wishlist references when the feature moves from identity into customer-owned commerce state.

Reference entry points

• Register or log in: Register new user and Login user.
• Maintain a session: Refresh token and Change password.
• Recover or verify an account: Create password reset link, Create email verification link, and Verify email.
• Users and organisations: Users and Organisations.
• Orders and customer groups: Orders and Customer Groups.
• Attributes and files: Attributes and Files.
• Saved carts: Cart reference.
• Wishlists: Wishlist reference.
• Complete contract: Auth OpenAPI.

For mixed domains such as Orders, Users, Organisations, Customer Groups, Cart, and Files, check the operation page's API label before choosing credentials or runtime placement. Trusted merchant administration belongs in Management API, while public catalog reads belong in Shopper or Search.

Session guidance

• Treat access tokens as credentials. Avoid logs and URLs.
• Confirm token field names, expiry fields, and refresh request shape in the reference.
• Keep password reset and email verification links short-lived in your application flow where possible.
• Design recovery states for expired credentials, invalid reset links, unverified emails, and logged-out cart or wishlist access.
• Keep customer-owned state separate from public catalog reads so storefront caching does not leak account-specific data.

Playground and reference

• Auth API playground loads /swagger/auth-api.json and lets you test current operations interactively.
• Auth endpoint reference groups identity and account-state endpoints.
• Cart reference and Wishlist reference cover authenticated commerce-state operations from the Auth API contract.
• Auth OpenAPI exposes the complete Auth API contract.

Version behavior

latest moves with the current recommended Auth API contract. Existing integrations should pin to a specific version route once archived versions are published.