Authentication

Overview

The Norman API uses the OAuth2’s standard flow to authenticate API clients. This secure authentication system ensures that only authorized users can access your data.

Norman API requests and responses are in JSON format. Once you register a user with the Norman API, you will receive an accessToken. This token should be securely stored in your database and associated with the user.

All subsequent API requests on behalf of your users must include the accessToken in the request headers, as per OAuth 2's protocols.

Example request:

curl -X 'GET'  
  '<https://sandbox.norman.finance/api/v1/companies/bec25987-a572-440f-8030-d4ddeaa05a73/taxes/reports/'>  
  -H 'accept: application/json'  
  -H 'Authorization: Bearer <accessToken>'

Key API Requests

[/api/v1/institution/](https://api-doc.norman.finance/reference/institutionuserscreatecreate)

1. Create a User and Get an Access Token

To create a user and receive an accessToken, you must make the following request. This token will allow you to make API calls on behalf of the user.

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/create/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "username": "newuser",  
      "email": "[email protected]",  
      "external_id": "7573b746-0be5-434a-90c3-37c1edb062bb"  
    }'

2. Refresh Token

Access tokens are valid for a limited period of time (usually 30 minutes). When the token expires, you must use the refreshToken to obtain a new accessToken without requiring the user to log in again.

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/token/refresh/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "refresh": "<refresh_token>"  
    }'

3. Verify Token

You can verify the validity of an existing token using the following request:

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/token/verify/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "token": "valid_token_example"  
    }'

4. Revoke Token

If you need to revoke a user’s token, use this endpoint to expire the token and prevent further API access:

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/token/expire/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "refresh": "sample_refresh_token"  
    }'

5. Generate New Access and Refresh Token

In cases where you need to generate a new accessToken and refreshToken for a user, you can use the following request. This may be necessary when setting up or recovering user credentials.

Example:

curl -X 'POST'  
  '<https://sandbox.norman.finance/api/v1/institution/users/token/retrieve/'>  
  -H 'accept: application/json'  
  -H 'Institution: institution_id:secret_key'  
  -H 'Content-Type: application/json'  
  -d '{  
      "username": "exampleuser",  
      "external_id": "123e4567-e89b-12d3-a456-426614174000",  
      "email": [[email protected]"  
    }'

By following these authentication steps, you can securely manage user sessions and integrate Norman’s full suite of API features. Always ensure that sensitive credentials (such as secretKey and accessToken) are securely stored and never exposed on the client-side.