How to Issue a Service Token

Here’s a step-by-step guide on how to issue a service token in Oz API 5 and 6.

1

Step 1

Authorize using your ADMIN account: {{host}}/api/authorize/auth.

Example request

curl -L 'https://{{host}}/api/authorize/auth' \
-H 'Content-Type: application/json' \
--data-raw '{
    "credentials": {
        "email": "[e-mail]",
        "password": "your_admin_password"
    }
}'

Example response

{
  …
    "user": {
        "user_type": "ADMIN",
  …
    },
    "access_token": "<token>",
    …
}

2

Step 2 (optional)

This step can be omitted if a company already exists.

As a user must belong to a company, create a company: call {{host}}/api/companies/ with your company name.

Example request

curl -L 'https://{{host}}/api/companies/'
-H 'X-Forensic-Access-Token: token_id'
-H 'Content-Type: application/json'
-d '{ "name": "your_company_name" }'

Example response

{
    "company_id": "company_id",
    "name": "your_company_name",
    "in_deletion": false,
    "technical_meta_data": {}
}

3

Step 3

Create a service user. Call {{host}}/api/users/ and write down user_id that you will get in response.

Example request

 curl -L 'https://{{host}}/api/users/'
-H 'X-Forensic-Access-Token: token_id'
-H 'Content-Type: application/json'
--data-raw '{
  "credentials": {
    "email": "<[e-mail]>",
    "password": "<your_service_user_password>"
  },
  "profile": {
    "company_id": " company_id",
    <!-- the next line is for API 6 -->
    "user_type": "CLIENT_SERVICE",
    "first_name": "first_name",
    "last_name": "last_name",
    "middle_name": "",
    "is_admin": false,
    <!-- the next line is for API 5 and below -->
    "is_service": true,
    "can_start_analyse_biometry": true,
    "can_start_analyse_collection": true,
    "can_start_analyse_documents": true,
    "can_start_analyse_quality": true
  }
}

Example response

{
    "user_id": "user_id",
    "user_type": "CLIENT_SERVICE",
     …
    "is_active": true,
     …
    "is_service": true
}

As in API 6.0, the logic of issuing a service token has slightly changed, here are examples for both API 6 and API 5 (and below) cases.

API 6

In the request body, define user_type as CLIENT_SERVICE.

{
  "credentials": {
    "email": " <[e-mail]> ",
    "password": "your_client_service_user_password"
  },
  "profile": {
    "company_id": "{{company_id}}",
    "user_type": "CLIENT_SERVICE",
    "first_name": "john",
    "last_name": "doe",
    "middle_name": "",
    "can_start_analysis_biometry": true,
    "can_start_analysis_collection": true,
    "can_start_analysis_documents": true,
    "can_start_analysis_quality": true
  }
}

API 5 and below

Set the is_service flag value to true.

{
    "credentials": {
        "email": "[e-mail]",
        "password": "your_client_service_user_password"
    },
    "profile": {
        "company_id": "{{company_id}}",
        "user_type": "CLIENT",
        "first_name": "john",
        "last_name": "doe",
        "middle_name": "",
        "is_admin": false,
        "is_service": true,
        "can_start_analyse_biometry": true,
        "can_start_analyse_collection": true,
        "can_start_analyse_documents": true,
        "can_start_analyse_quality": true
    }
}

4

Step 4

If you need to obtain the service token to use it, for instance, with Web SDK, authorize as ADMIN (same as in Step 1) and call:

• API 6: {{host}}/api/authorize/service_token/{user_id} with user_id from the previous step.

• API 5 and below: {{host}}/api/authorize/service_token.

Example request

curl -L 'https://{{host}}/api/authorize/service_token/{{user_id}}' \
-H 'X-Forensic-Access-Token: token_id' \
-H 'Content-Type: application/json'

Example response

{
    "token_id": "token_id",
    "user_id": "user_id",
    "access_token": "service_token",
    "expire_date": 1904659888.282587,
    "session_id": 0
}

In response, you will get a service token that you can use in any service processes.

For Web SDK, specify this token’s value as api_token in the Web Adapter configuration file.