Getting Started with Authentication

Tokens Overview

Authentication App Access Token (JWT)

Use for: Calling protected Authentication endpoints.

Header: Authorization: Bearer <current_auth_access_token>

Default validity: 7 days

Ejento Access Token

Use for: Ejento Platform APIs (besides Authentication endpoints).

Header: Typically Authorization: Bearer <ejento_access_token>

Default validity: 7 days

⚠️ These tokens serve different purposes and are not interchangeable.

When to Use Which Endpoint

Endpoint: POST /auth-service/api/v2/login/access-token

Body (x-www-form-urlencoded):

username

password

Returns: Both tokens (Authentication App access token and Ejento access token)

Use when: The user has a password

2. Passwordless (Email-based Code → Exchange)

Step 1: Request Token

Endpoint: POST /auth-service/api/v2/login/passwordless/request-token

Body (JSON):

{ "email": "[email protected]" }

Sends a single-use exchange code to the user’s email (expires in 10 minutes)

Step 2: Exchange Code for Tokens

Endpoint: POST /auth-service/api/v2/login/passwordless/exchange-tokens

Body (JSON):

{ "code": "<opaque-exchange-code-from-email>" }

Returns: Both tokens

Use when: The user does not use a password to sign in

Endpoint: POST /auth-service/api/v2/users/signup

Body (JSON):

{
  "email": "[email protected]",
  "full_name": "User Name",
  "password": "password123"
}

Returns: The created user

On first login, you’ll obtain both tokens

4. Refresh Authentication App Access Token

Endpoint: POST /auth-service/api/v2/users/refresh-access-token

Header: Authorization: Bearer <current_auth_access_token>

Returns: Refreshed Authentication App Access Token and Ejento Access Token

5. Update Own Password

Endpoint: PATCH /auth-service/api/v2/users/me/password

Header: Authorization: Bearer <current_auth_access_token>

Body (JSON):

{
  "current_password": "old_password",
  "new_password": "new_password123"
}

Typical Flows

Password-Based Authentication Flow

Call /auth-service/api/v2/login/access-token

Store both tokens

Use:

Authentication App access token → for Authentication APIs

Ejento access token → for Ejento Platform APIs

Passwordless Authentication Flow

Call /auth-service/api/v2/login/passwordless/request-token

Retrieve the email code

Call /api/v2/login/passwordless/exchange-tokens with the code

Store both tokens and use as above

Keeping Sessions Fresh

Before the Authentication App access token expires, call /auth-service/api/v2/users/refresh-access-token to get refreshed tokens (Ejento Access Token and Authentication App Access Token).

Notes

The email exchange code is single-use and expires in 10 minutes.

It is not a token itself — you must exchange it to receive both tokens.

Never send tokens in URLs.

Always include tokens in the Authorization header when calling APIs.

Getting Started with Authentication

Tokens Overview#

Authentication App Access Token (JWT)#

Ejento Access Token#

When to Use Which Endpoint#

1. Login with Email/Password#

2. Passwordless (Email-based Code → Exchange)#

Step 1: Request Token#

Step 2: Exchange Code for Tokens#

3. Sign Up#

4. Refresh Authentication App Access Token#

5. Update Own Password#

Typical Flows#

Password-Based Authentication Flow#

Passwordless Authentication Flow#

Keeping Sessions Fresh#

Notes#

Tokens Overview

Authentication App Access Token (JWT)

Ejento Access Token

When to Use Which Endpoint

1. Login with Email/Password

2. Passwordless (Email-based Code → Exchange)

Step 1: Request Token

Step 2: Exchange Code for Tokens

3. Sign Up

4. Refresh Authentication App Access Token

5. Update Own Password

Typical Flows

Password-Based Authentication Flow

Passwordless Authentication Flow

Keeping Sessions Fresh

Notes