Skip to main content

Authentication and Authorization

Overview​

The Kinver Export API utilizes a token-based authentication mechanism to ensure secure access to endpoints. Users must authenticate by providing valid API credentials to receive an access token, which must be included in subsequent API requests for authorization.

Kinver recommends a dedicated API user account for programmatic access to the API. This account should have the necessary permissions to perform the required actions and should not be shared with multiple users.

The base URL for all API endpoints is https://api.kinver.no.

Authenticating with the API​

Endpoint: /auth/token​

  • Method: POST
  • Base URL: https://api.kinver.no
  • Full URL: https://api.kinver.no/auth/token
  • Description: This endpoint is used to authenticate the user by their email and password. Upon successful authentication, it returns an access token and its expiry time.

Request Body​

  • email (string): The user's email address. Must be a valid email format.
  • password (string): The user's password. The password must be at least 6 characters long.

Example Request​

Request payload should be JSON

POST /auth/token
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

Successful Response​

  • token (string): A JWT (JSON Web Token) used for subsequent requests to authenticate the user.
  • expiresAt (string): The ISO string representing the expiry date and time of the token.

Example Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2023-04-05T14:48:00.000Z"
}

Error Response​

  • 401 Unauthorized: This status is returned if the email or password is incorrect, indicating a failed login attempt.

Throttling​

The login endpoint is protected with rate limiting to prevent brute-force attacks. Users are limited in the number of login attempts they can make within a specified timeframe.

Usage of the Token​

Once obtained, the token must be included in the kauth header of subsequent API requests.

The token includes claims such as the user's email, a unique user ID, and their authentication status, which are used for authorization purposes within the API.

Example​

GET /some/protected/endpoint
Host: api.kinver.no
kauth: <token>

Token Validation​

The API validates the provided token on each request to protected endpoints. If the token is missing, expired, or invalid, the API responds with a 401 Unauthorized status.

Token payload includes standard JWT fields along with additional claims specific to our authentication system.

Security Notes​

Passwords are not stored within our API but are verified using an Identity Toolkit, ensuring a secure authentication process.

It is crucial to transmit the authentication credentials over a secure channel (HTTPS) to prevent exposure to unauthorized entities.