2. Authentication

This section covers authentication and related topics. Please ensure you have read the previous section providing an overview of the API.

Users and Teams

Nearly all API calls are done on behalf of a user. The user is the primary identity. All clients should provide a way to register and authenticate users. Users always have the following properties:

id — a unique ID (UUID format) identifying the user.
email — a user’s email address which also uniquely identifies them to the API.
name — a human readable identifier for the user.
password — a secret password known only to the user.

Users can also be organized into teams for more efficient management of responsibility and roles. Teams have the following properties:

id — a unique ID (UUID format) identifying the team.
name — a unique, human readable identifier for the team.
members — a list of users who belong to the team.

API Keys

API keys are secret token strings that are attached to resources such as an authenticated user. API keys come in two flavours. Live keys are prefixed with user-live- and should be used in production. Test keys, prefixed with user-test- can be used in development. Any data provided to the API with a test key will be removed on a regular basis. Furthermore, jobs which are created with a test key will not be curated by our human experts.

Authentication HTTP Header

In order to perform authentication and authorization, the API requires a user-attached API key for most endpoints. This key must be provided as the username with an empty password as part of HTTP Basic Authentication scheme. For basic authentication, the username must be appended with a colon indicating an empty password, then Base64 encoded and given as a header Authentication: Basic ${base64encode(token + ":")}.

Example:

For example, given the token: user-live-632a5a63-d6d6-4246-91ca-d546632698d3, in a web browser environment, you can generate the authorization header:

fetch(https://api.innodata.com/v1.1/users/me", {
  headers: {
    "Content-type": "application/json",
    Authentication: `Basic ${btoa("user-live-632a5a63-d6d6-4246-91ca-d546632698d3:")}`,
  },
})
  .then(res => res.json())
  .then(res => {
    console.log("My name is", res.response.name);
  })
  .catch(err => {
    console.error(err);
  });

Getting an API Key

Retrieving an API key must be done in one of two ways.

Create a new user.
Authenticate as an existing user.

Example:

Creating a new user:

POST https://api.innodata.com/v1/users
Content-type: application/json
Body:
{
  "name": "My Name Goes Here",
  "email": "me@example.com",
  "password": "my secret passw0rd!!!",
  "demo": false
}

Response:
{
  "success": true,
  "status_code": 201,
  "tracking": "05732019-889d-4b43-8049-cf0dfe3c0d34",
  "response": {
    "activated": false,
    "api_keys": {
      "live": null,
      "test": null,
    },
    "email": "me@example.com",
    "email_verified": false,
    "id": "5a2e5257-404d-4aaf-86c4-b1c2a1ff886b",
    "is_demo": false,
    "name": "My Name Goes Here"
  }
}

Example:

Authenticating as a user (logging in):

POST https://api.innodata.com/v1.1/users/login
Content-type: application/json
Body:
{
  "authentication_method": "password",
  "username": "me@example.com",
  "password": "my secret passw0rd!!!"
}

Response:
{
  "success": true,
  "status_code": 200,
  "tracking": "05732019-889d-4b43-8049-cf0dfe3c0d34",
  "response": {
    "activated": true,
    "api_keys": {
      "live": "user-live-632a5a63-d6d6-4246-91ca-d546632698d3",
      "test": "user-test-29a846c5-f990-4fd1-b1c5-0a5f81f1b8a7",
    },
    "email": "me@example.com",
    "email_verified": true,
    "id": "5a2e5257-404d-4aaf-86c4-b1c2a1ff886b",
    "is_demo": false,
    "name": "My Name Goes Here"
  }
}

API Key => User Lookup

In order to lookup the details of a user, given API key, use the GET /users/me endpoint.

Example:

GET https://api.innodata.com/v1.1/users/me
Authorization: Basic dXNlci1saXZlLTYzMmE1YTYzLWQ2ZDYtNDI0Ni05MWNhLWQ1NDY2MzI2OThkMzo=

Response:
{
  "success": true,
  "status_code": 200,
  "tracking": "05732019-889d-4b43-8049-cf0dfe3c0d34",
  "response": {
    "activated": true,
    "api_keys": {
      "live": "user-live-632a5a63-d6d6-4246-91ca-d546632698d3",
      "test": "user-test-29a846c5-f990-4fd1-b1c5-0a5f81f1b8a7",
    },
    "email": "me@example.com",
    "email_verified": true,
    "id": "5a2e5257-404d-4aaf-86c4-b1c2a1ff886b",
    "is_demo": false,
    "name": "My Name Goes Here"
  }
}