Authentication & Account Management

Overview

The Nomad Media API uses JWT Bearer tokens for authentication. All authenticated endpoints require a valid access token in the Authorization header:

Authorization: Bearer <your-access-token>

Access tokens have a limited lifetime (indicated by ExpirationSeconds in the login response). Use the refresh token to obtain a new access token before the current one expires.

Base Routes

Authentication Flow

Standard Registration & Login

1. POST /account/register          - Create a new account
2. POST /account/verify            - Verify email with the code sent to user
3. POST /account/login             - Authenticate and receive JWT token
4. Use Bearer token for all authenticated requests
5. POST /account/ping              - Keep session alive (periodic)
6. POST /account/refresh-token     - Get new token before expiration
7. POST /account/logout            - End session

Guest User Flow

1. POST /account/invite-user       - Invite guests with content access (authenticated user)
2. POST /account/register-guest    - Guest completes registration via invitation
3. POST /account/login             - Guest logs in with their credentials

Password Reset Flow

1. POST /account/forgot-password   - Request a password reset code
2. POST /account/reset-password    - Submit the code and set a new password

Account Statuses

When an account is in a non-standard state, the API returns a LoginStatus value indicating what action is needed:

Session Management

Keeping Sessions Alive

Use POST /account/ping periodically to keep a session active. The response includes a PingStatus:

Single-Session Enforcement

When enabled, only one active session per user is allowed. If a user logs in from a new device or browser, the previous session is replaced and will return SessionDeactivated on the next ping.

Session Status Management (Admin)

Administrators can manage user sessions via the Admin API:

• GET /admin/user-session/{id} - View session details
• POST /admin/user-session - Change session status (e.g., kick user, restrict chat)

Available session statuses:

Token Lifecycle

Guest User Management

Inviting Guests

Use POST /account/invite-user to invite users as guests with access to specific content:

• Provide an array of email addresses and the ContentDefinitionId for the content to share
• Each invited user receives an email with registration instructions
• New guest accounts are created with PendingInvitation status

Removing Guests

Use POST /account/remove-user to revoke a guest's content access:

• Specify the user by UserId or Emails along with the ContentId
• The user's sessions are terminated
• If the user has no remaining content access, their account may be expired or removed

Live Channel Sessions (Portal)

GET /user-session/{id} returns the users associated with a live channel:

• Items: Currently online users with active sessions
• RelatedItems: Offline shared-access users (with " (offline)" suffix) and users with pending invitations
• Currently only supports live channel content definitions

Person Management

The person API manages person entities for facial recognition matching:

Face Match Types

Health Checks

Common Error Responses