Overview

The N-central Authentication APIs provide a secure, token-based authentication system for accessing N-central services. Using JWT (JSON Web Token) technology, these APIs enable you to authenticate users, manage access tokens, and maintain secure sessions for your N-central integrations.

API Methods

List Authentication Links

Returns available authentication-related endpoints for service discovery.

Required Parameters

None - this is an unauthenticated endpoint

Example Request

GET /api/auth

Example Response

{
    "authenticate": "/api/auth/authenticate",
    "refresh": "/api/auth/refresh",
    "validate": "/api/auth/validate"
}

Authenticate

Obtains access and refresh tokens using an N-central User-API Token.

Required Parameters

Authorization: Bearer token containing N-central User-API Token (JWT)

Optional Headers

X-ACCESS-EXPIRY-OVERRIDE: Format: (time)(unit). Example: "120s" for 120 seconds
- Units: 's' (seconds), 'm' (minutes), 'h' (hours)
- Cannot exceed system-wide setting (default 1h)
X-REFRESH-EXPIRY-OVERRIDE: Same format as above
- Cannot exceed system-wide setting (default 25h)

Example Request

POST /api/auth/authenticate
Authorization: Bearer <YOUR_JWT>

Example Response

{
    "tokens": {
        "access": {
            "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1MjZjMTjI0M30.try6YwSXhu1qh1iyBPonWVfxLexlNavXkRqQaeY2uzo",
            "type": "Bearer",
            "expirySeconds": 3600
        },
        "refresh": {
            "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1I2OTQ0M30.T_yn88Xg258liJa5AwLq011-TWDMWMKVVyR5AYOM3os",
            "type": "Body",
            "expirySeconds": 90000
        }
    },
    "refresh": "/api/auth/refresh",
    "validate": "/api/auth/validate"
}

Refresh Token

Obtains new access and refresh tokens using a valid refresh token.

Required Parameters

Request Body: Refresh token as plain text

Optional Headers

Same expiry override options as authenticate endpoint

Example Request

POST /api/auth/refresh
Content-Type: text/plain

<refresh-token>

Validate Token

Checks if an access token is valid.

Required Parameters

Authorization: Bearer token containing access token to validate

Example Request

GET /api/auth/validate
Authorization: Bearer <access-token>

Example Response

{
    "message": "The token is valid."
}

Key Features

JWT-Based Authentication

Secure authentication using JSON Web Tokens with configurable expiry times for both access and refresh tokens.

Token Lifecycle Management

Complete token management system with separate access and refresh tokens, allowing for secure token renewal without requiring re-authentication.

Flexible Token Configuration

Customizable token expiry times through header overrides, within system-defined limits.

Implementation Steps

Initial Token Generation
- Navigate to: Administration → User Management → Users → Click on user → API Access → GENERATE JSON WEB TOKEN
- Store the generated JWT securely - this is your N-central User-API Token
Authentication Flow
- Exchange N-central User-API Token for access/refresh tokens via authenticate endpoint
- Store returned tokens securely
- Use access token for API requests
- Refresh tokens before expiry
Token Management
- Monitor access token expiration (default 1 hour)
- Use refresh token to obtain new tokens
- Validate tokens when needed
- Note refresh token expiration (default 25 hours)

Best Practices

Token Security

Store N-central User-API Token securely
Never expose tokens in client-side code
Implement secure token storage
Clear tokens on session end

Token Lifecycle

Track token expiration times
Refresh tokens before expiry
Maintain single source for token management
Handle token invalidation gracefully

Error Handling

Handle authentication failures appropriately
Implement token refresh on expiry
Monitor authentication patterns
Log authentication issues securely

For detailed specifications, additional error codes, and advanced usage scenarios, refer to the complete API documentation.