Authentication API Documentation

Authentication API Documentation

This document provides documentation for the Authentication API endpoints available in the Points.Api system.

Table of Contents

• Authentication
• Endpoints
  • Get Auth Token
• Authentication Handler
• JWT Token Structure

Authentication

The Points.Api system uses a two-step authentication process:

1. API Key Authentication: Initial authentication is done using an API key provided in the request header.
2. JWT Token Authentication: After successful API key authentication, a JWT token is issued which is used for subsequent requests.

Endpoints

Get Auth Token

Generates a JWT token for authenticated API clients.

URL: /api/Authentication/getauthtoken

Method: GET

Auth required: Yes (API Key Authentication)

Headers:

• apikey (string) - The API key associated with a partner

Success Response:

• Code: 200 OK
• Content: JWT token

Error Response:

• Code: 401 Unauthorized
• Content: Error message

Example Request:

GET /api/Authentication/getauthtoken HTTP/1.1
Host: your-api-domain.com
apikey: your-partner-api-key

Example Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Authentication Handler

The authentication process is handled by a custom AuthenticationHandler that validates API keys against partner records in the database.

Authentication Flow

1. The client includes an API key in the request header (apikey).
2. The AuthenticationHandler validates the API key against the list of registered partners.
3. If valid, the handler creates a ClaimsPrincipal with claims for:
   • PartnerId: The ID of the partner
   • PartnerName: The name of the partner
4. The Authentication controller then uses these claims to generate a JWT token.
5. The client uses this JWT token for subsequent API requests.

JWT Token Structure

The JWT token generated by the system has the following characteristics:

• Algorithm: HMAC SHA-256 (HS256)
• Issuer: Configured in application settings (Jwt_Issuer)
• Expiration: 5 minutes from issuance
• Claims:
  • PartnerId: The ID of the partner
  • PartnerName: The name of the partner

Using the JWT Token

After obtaining a JWT token, include it in the Authorization header of subsequent requests:

Authorization: Bearer {your_jwt_token}

The token will be valid for 5 minutes, after which a new token must be obtained.

Security Considerations

• API keys should be kept secure and not exposed in client-side code.
• JWT tokens have a short expiration time (5 minutes) to minimize the risk of token theft.
• All API communications should be over HTTPS to prevent interception of tokens.