Skip to content

Authentication

All AmpNexus APIs use JWT Bearer tokens for authentication. Tokens are issued by AmpNexus Auth and must be included in the Authorization header of all API requests.

Overview

AmpNexus Auth provides identity and access management for all API resources. Applications authenticate users and receive JWT tokens that grant access to tenant-scoped resources.

Authentication Flows

Authorization Code Flow (Web Applications)

Recommended for web applications with a backend server.

sequenceDiagram
    participant User
    participant App as Web Application
    participant Auth as AmpNexus Auth
    participant API as AmpNexus API

    User->>App: Access application
    App->>Auth: Redirect to login page
    Auth->>User: Show login form
    User->>Auth: Submit credentials
    Auth->>Auth: Validate credentials
    Auth->>App: Redirect with auth code
    App->>Auth: Exchange code for tokens
    Auth->>App: Return access_token + refresh_token
    App->>API: Request with Bearer token
    API->>API: Validate JWT
    API->>App: Return data
    App->>User: Display data

Client Credentials Flow (Service-to-Service)

Used for backend services and system integrations.

sequenceDiagram
    participant Service as Your Service
    participant Auth as AmpNexus Auth
    participant API as AmpNexus API

    Service->>Auth: POST /oauth2/token<br/>(client_id + client_secret)
    Auth->>Auth: Validate credentials
    Auth->>Service: Return access_token
    Service->>API: Request with Bearer token
    API->>API: Validate JWT + check scopes
    API->>Service: Return data

API Key Flow (Simple Integration)

For simple integrations and API testing.

sequenceDiagram
    participant Client
    participant API as AmpNexus API
    participant Auth as Auth Service

    Client->>API: Request with X-Api-Key header
    API->>Auth: Validate API key
    Auth->>Auth: Check permissions
    Auth->>API: Return tenant + scopes
    API->>API: Process request
    API->>Client: Return data

Token Format

JWT Structure

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "abc123"
  },
  "payload": {
    "aud": "https://api.ampnexus.app",
    "exp": 1704067200,
    "iat": 1704063600,
    "iss": "https://auth.ampnexus.app",
    "sub": "00000000-0000-0000-0000-000000000000",
    "email": "user@example.com",
    "roles": ["tenant-admin", "device-operator"],
    "tenant_id": "ten_abc123",
    "tenant_slug": "my-tenant"
  }
}

Key Claims

  • sub - User ID
  • email - User email address
  • roles - Array of role names
  • tenant_id - Tenant identifier
  • tenant_slug - Human-readable tenant identifier
  • exp - Token expiration timestamp
  • iss - Token issuer (AmpNexus Auth)
  • aud - Intended audience (API base URL)

Making Authenticated Requests

HTTP Header

Include the JWT token in the Authorization header:

GET /reporting/v1/tenants/{tenant_slug}/dashboard/overview HTTP/1.1
Host: api.ampnexus.app
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

cURL Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  https://api.ampnexus.app/reporting/v1/tenants/{tenant_slug}/dashboard/overview

JavaScript Example

const response = await fetch(
  'https://api.ampnexus.app/reporting/v1/tenants/{tenant_slug}/dashboard/overview',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();

Python Example

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.ampnexus.app/reporting/v1/tenants/{tenant_slug}/dashboard/overview',
    headers=headers
)

data = response.json()

Token Lifecycle

Token Expiration

sequenceDiagram
    participant App
    participant Auth as AmpNexus Auth
    participant API as AmpNexus API

    App->>API: Request with access_token
    API->>API: Check exp claim
    alt Token expired
        API->>App: 401 Unauthorized
        App->>Auth: POST /oauth2/token<br/>(grant_type=refresh_token)
        Auth->>App: Return new access_token
        App->>API: Retry with new token
        API->>App: Return data
    else Token valid
        API->>App: Return data
    end

Refresh Token Flow

  1. Store refresh token securely (never in browser localStorage)
  2. When access token expires (401 response)
  3. Use refresh token to get new access token
  4. Retry the original request
  5. If refresh fails, redirect to login
# Refresh token request
curl -X POST https://auth.ampnexus.app/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Scopes and Permissions

Role-Based Access

Access to resources is determined by:

  1. Tenant membership - User must belong to the tenant
  2. Role assignment - User must have appropriate roles
  3. Resource ownership - Some resources are user-specific

Common Roles

  • tenant-admin - Full access to tenant resources
  • device-operator - Manage devices and charging operations
  • billing-viewer - View reports and financial data
  • api-user - Basic API access

Checking Permissions

The API validates:

graph TD
    A[API Request] --> B{Valid JWT?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{Correct Tenant?}
    D -->|No| E[403 Forbidden]
    D -->|Yes| F{Has Required Role?}
    F -->|No| E
    F -->|Yes| G{Resource Exists?}
    G -->|No| H[404 Not Found]
    G -->|Yes| I[200 OK + Data]

Error Responses

401 Unauthorized

Token is missing, invalid, or expired:

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

403 Forbidden

Token is valid but lacks required permissions:

{
  "error": "forbidden",
  "message": "Insufficient permissions for this resource"
}

Security Best Practices

Token Storage

✅ DO: - Store access tokens in memory (frontend) - Store refresh tokens in httpOnly cookies (backend) - Use secure, httpOnly cookies for sensitive tokens - Implement token rotation

❌ DON'T: - Store tokens in localStorage (XSS risk) - Expose tokens in URLs or logs - Share tokens between applications - Store tokens in source code

Token Transmission

  • Always use HTTPS
  • Never send tokens in query parameters
  • Use the Authorization header
  • Validate SSL certificates

Token Validation

The API validates every token by:

  1. Verifying signature (RS256)
  2. Checking expiration (exp claim)
  3. Validating issuer (iss claim)
  4. Verifying audience (aud claim)
  5. Checking tenant membership
  6. Validating roles and permissions

AmpNexus Auth Endpoints

Auth: https://auth.ampnexus.app
OAuth: https://auth.ampnexus.app/oauth2

Getting API Credentials

To obtain API credentials for your application:

  1. Contact AmpNexus support: support@ampnexus.co.uk
  2. Provide your use case and required scopes
  3. Receive client_id and client_secret
  4. Store credentials securely
  5. Never commit credentials to source control

Testing Authentication

Use the /version endpoint to test authentication (no special permissions required):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.ampnexus.app/reporting/v1/version

Successful response:

{
  "version": "1.2.3",
  "git_commit": "abc123",
  "build_timestamp": "2025-01-15T10:30:00Z"
}

Authentication

AmpNexus APIs are protected by api-auth. Clients must authenticate using JWT bearer tokens or API keys.

1. Get API Keys

Partners and CPOs can request API keys via the AmpNexus Portal.
Keys are tied to a tenant and issued with minimal scopes.

Example header: 

Authorization: Bearer apikey:<id>:<secret>

2. JWT Tokens (OAuth2)

Portal/mobile clients authenticate via AmpNexus Auth OAuth2: - client_id: provided per tenant - scope: space-delimited (e.g., CP_DEVICE_READ CP_TXN_READ) - audience: https://api.ampnexus.app

Request a token: 

curl -X POST https://auth.ampnexus.app/oauth2/token   -d 'client_id=...'   -d 'client_secret=...'   -d 'grant_type=client_credentials'   -d 'scope=CP_DEVICE_READ CP_TXN_READ'

Use the token: 

curl https://api.ampnexus.app/api/chargepoint/v1/tenants/demo/devices   -H "Authorization: Bearer <token>"

3. Identity Headers

api-auth injects identity headers after verification: - X-Auth-Subject
- X-Auth-Mode (customer | platform | apikey | service)
- X-Auth-Scopes
- X-Auth-Tenant

4. Roles & Scopes

See each API page for role definitions.
Example: chargepoint-api - CP_VIEWER → CP_DEVICE_READ CP_TXN_READ - CP_ADMIN → full device, txn, logs, settings