Authentication & Tokens

Security Admin Only

Authentication methods overview

nara supports multiple authentication methods depending on how you access the platform:

Web login

The primary authentication method for web users. nara supports SSO, social login, email/password, and multi-factor authentication. When you log in through the nara web application, the platform handles the entire authentication flow.

JWT tokens

JSON Web Tokens are used by the Edge Connector and API clients to authenticate with the platform. JWTs contain claims about the user’s identity and organization membership and are validated on every request.

Server tokens

Long-lived tokens generated from the Settings page for programmatic API access. Server tokens are bound to your organization and can be used in automation scripts, CI/CD pipelines, and third-party integrations.

Generating server tokens

Server tokens provide programmatic access to the nara API without requiring interactive login. To generate a token:

1. Navigate to Settings > API & Security.

2. Click Generate Token.

3. Give the token a name that describes its purpose (e.g., “CI Pipeline”, “Monitoring Script”, “External Integration”).

4. Click Create. The token is displayed once — copy it immediately and store it securely.

5. The token appears in your token list with its name, creation date, and last-used timestamp.

Caution

The token value is shown only once at creation time. If you lose it, you must generate a new token. The platform does not store the plain-text token value.

Token scoping

Server tokens are scoped to your organization:

• Organization-bound — each token is tied to the organization in which it was created. It cannot access resources in other organizations.
• Full API access — server tokens grant access to all API endpoints available to your organization, subject to your license tier.
• No user context — server tokens act on behalf of the organization, not a specific user. Actions performed with a server token are logged with the token’s name for auditing.

Using tokens in API requests

Include the server token in the Authorization header of your HTTP requests:

curl -X GET https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer <YOUR_SERVER_TOKEN>" \
  -H "Content-Type: application/json"

All API endpoints accept Bearer token authentication. The token is validated on every request — if the token is revoked or the organization is deactivated, the request is rejected with a 401 Unauthorized response.

Example: listing runnable functional agents

curl -X GET https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_tk_abc123..." \
  -H "Content-Type: application/json"

Example: triggering a functional agent run

curl -X POST https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_tk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "summarizeTicket",
    "args": {
      "ticketNumber": "1234"
    }
  }'

Token security best practices

Rotate regularly

Generate new tokens periodically and revoke old ones. This limits the window of exposure if a token is compromised. Establish a rotation schedule (e.g., every 90 days) and automate the process where possible.

Never commit to source control

Tokens should never appear in code repositories, configuration files checked into Git, or build artifacts. Use .gitignore to exclude any files that contain tokens.

Use environment variables

Store tokens in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, GitHub Secrets) rather than hardcoding them in scripts or configuration files.

Revoke unused tokens

Regularly review your token list under Settings > API & Security. Revoke any tokens that are no longer in use or whose purpose is no longer relevant.

Revoking tokens

To revoke a server token:

1. Navigate to Settings > API & Security.

2. Find the token in the list.

3. Click Revoke and confirm.

4. The token is invalidated immediately. Any requests using this token will receive a 401 Unauthorized response.

Note

Revoking a token is permanent. If you need access again, generate a new token.

Desktop auth flow for Edge Connector

The Edge Connector uses a specialized desktop authentication flow to obtain JWT tokens without requiring server token management:

How it works

The desktop auth flow is a browser-based OAuth flow initiated from the CLI:

1. The Edge Connector sends a request to the platform with a device name and device ID.
2. The platform returns an authorization code and a browser URL.
3. The CLI opens the browser, where the user logs in and approves the connection.
4. The CLI retrieves a JWT token and stores it locally for subsequent API calls.

This flow is ideal for desktop and on-premises installations where an interactive login is possible.

When to use what

Scenario	Recommended auth method
Web application login	Web login (automatic)
Desktop Edge Connector	Desktop auth flow (browser OAuth)
Headless server Edge Connector	Deployment credentials (ID + secret)
CI/CD pipelines	Server token
Monitoring scripts	Server token
Third-party integrations	Server token

For detailed information about Edge Connector authentication modes, see the Edge Connector Authentication page.

Next steps

Edge Connector Authentication Detailed guide to Edge Connector authentication modes and token management.

Organization Manage organization settings and member access.

Roles & Permissions Control who can generate tokens and access security settings.