## Authorize (Get user API key)

This endpoint authenticates an Xtracta user and returns the API key assigned to that user. Authenticate with either a current `login_token`, or the user's `emailaddress` and `password`.

{% callout type="warning" %}
**Credential security:** Call this endpoint only from a trusted backend. Treat passwords, login tokens, and returned API keys as secrets, and never expose them in browser-delivered code.
{% /callout %}

## POST Parameters

{% apiTable %}
| Parameter | Required | Value | Description |
|-----------|----------|-------|-------------|
| `login_token` | {% requiredIcon type="conditional" /%} | `{string}` | A current login token. Supply this by itself, or use `emailaddress` and `password` instead. |
| `emailaddress` | {% requiredIcon type="conditional" /%} | `{email}` | The user's email address. Required when `login_token` is not supplied. |
| `password` | {% requiredIcon type="conditional" /%} | `{string}` | The user's password. Required with `emailaddress` when `login_token` is not supplied. |
{% /apiTable %}

## Code Examples

The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.

{% callout type="warning" %}
Send authentication values only to your own backend. Do not call the Xtracta endpoint directly from browser code.
{% /callout %}

{% tabbedCodeExamples %}
```bash
curl --request POST 'https://api-app.xtracta.com/v1/user/authorize' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'login_token=<LOGIN_TOKEN>'
```

```php
<?php
$endpoint = 'https://api-app.xtracta.com/v1/user/authorize';
$payload = [
    'login_token' => '<LOGIN_TOKEN>',
];

$curl = curl_init($endpoint);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException('Xtracta returned HTTP ' . $status . ': ' . $body);
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
```

```python
import os
import requests

response = requests.post(
    "https://api-app.xtracta.com/v1/user/authorize",
    headers={"Accept": "application/json"},
    data={
        "login_token": "<LOGIN_TOKEN>",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
```

```javascript
const body = new URLSearchParams({
  "login_token": "<LOGIN_TOKEN>",
});

const response = await fetch('https://api-app.xtracta.com/v1/user/authorize', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body,
});

if (!response.ok) {
  throw new Error('Xtracta returned HTTP ' + response.status + ': ' + await response.text());
}

const data = await response.json();
```

```csharp
using System.Net.Http.Headers;

using var client = new HttpClient {
    Timeout = TimeSpan.FromSeconds(30)
};
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

using var content = new FormUrlEncodedContent(new Dictionary<string, string> {
    ["login_token"] = "<LOGIN_TOKEN>",
});

using var response = await client.PostAsync("https://api-app.xtracta.com/v1/user/authorize", content);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
```

```jsx
async function callXtracta() {
  const response = await fetch('/api/xtracta/user/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      "login_token": "<LOGIN_TOKEN>",
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}
```
{% /tabbedCodeExamples %}

## Sample Request

Using a login token:

```
POST https://api-app.xtracta.com/v1/user/authorize HTTP/1.1
Content-Type: application/x-www-form-urlencoded

login_token=<LOGIN_TOKEN>
```

Using an email address and password:

```
POST https://api-app.xtracta.com/v1/user/authorize HTTP/1.1
Content-Type: application/x-www-form-urlencoded

emailaddress=user@example.com&password=<PASSWORD>
```

## Sample Response

{% tabbedResponse  title="" %}


```xml
<?xml version="1.0" encoding="UTF-8"?>
<user_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <user_id>12345</user_id>
    <user_name>John Doe</user_name>
    <api_key>example-api-key</api_key>
</user_response>
```

{% /tabbedResponse %}

## Schema Definition


### Response Elements

{% apiTable %}
| Element | Description |
|---------|-------------|
| `<status>` | The response status code. |
| `<message>` | Human-readable information about the operation. |
| `<user_id>` | The authenticated user's ID. |
| `<user_name>` | The authenticated user's name. |
| `<api_key>` | The API key assigned to the authenticated user. |
{% /apiTable %}

{% tabbedSchema title="" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="user_response">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="status" type="xs:positiveInteger"/>
        <xs:element name="message" type="xs:string"/>
        <xs:element name="user_id" type="xs:positiveInteger" minOccurs="0"/>
        <xs:element name="user_name" type="xs:string" minOccurs="0"/>
        <xs:element name="api_key" type="xs:string" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
```

{% /tabbedSchema %}
## Error Responses

For JSON and XML responses generated by this endpoint, the response is wrapped in `user_response` and includes the HTTP status code and a `message`.

{% apiTable %}
| Status | Message | Description |
|---|---|---|
| `401` | Invalid authentication information | Supply a valid login token, or a valid email address and password. |
| `401` | Login token is expired | Request a new login token and retry. |
| `500` | multiple application for user(...) found | The user has an ambiguous API-application mapping. Contact support. |
| `500` | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the request parameters and timestamp if it persists. |
{% /apiTable %}

{% callout type="note" %}
This endpoint performs user authentication, so its expected credential failures are listed above. IP-access-control and rate-limit failures may still be returned before authorization completes.
{% /callout %}


Authorize

Logging In

Overview

Home Page

Supported Languages

Get started

My Account

Workflow Overview

Uploading Documents

ELS Overview

Splitting Pages

Engine Learning Screen

New ELS Overview

Edit Document and Pages

Change Field Highlight Color

Learn & Extract

Learn & Extract (Previously Auto Line Extraction )

New Engine Learning Screen (New ELS)

User Manual

Get Document(s)

Update Document

Upload Document

Open Document UI

Open Document Upload UI

Open Reassign Pages

Documents

Create Batch

Update Batch

Get Batches

Get Batch Workflow

Batches

Get Tracking

Update Tracking Status

Tracking

Open Dashboard

Open Tracking Dashboard

Dashboard

Get Databases

Add Database

Update Database

Delete Database

Get Columns

Update Column

Add Column

Delete Column

Get Data

Add Data

Update Data

Delete Data

Database

Provisioning

Get Workflow

Update Workflow

Add Workflow from Template

Clone Workflow

Workflow

Delete Group

Add Group

List Group

Group

Get User

Add User

Update User

Delete User

Get Login Token

User

Open Billing UI

Get Plans

Get Usage

Renew/Upgrade/Downgrade Plan

Get Billing History

Order Pack

Billing

Announcements

API Manual

Billing Settings

General Settings

Groups

OCR Override

Time Alerts

Confidence

Extraction & Classification

Clone a workflow

Reassignment / Output Non-API

Conditions

Permissions

Auto Deletion

AI Data Transformation

Fields

Transformation Order

Advanced Transformation

Workflow Details

Strip & Replace Rules

Creating a workflow

Input & Document Flow

Extraction Helper

Advanced Validation

Workflows

Users

Admin Manual

Databases

IP Access Control

Client Applications

Client Push Application

Applications

Alerts

Single Sign On (SSO)

Peppol Participants

General FAQs

Why is a document locked?

Which URL`s are needed for Xtracta to go through a firewall?

What type of documents are accepted by Xtracta?

What is a workflow?

What are the different statuses for a document?

What are the status for a document?

What does training a document mean?

What are the options when a document is selected?

What is Regex?

How does a document get a class and a designn?

How does a document get a class and a design?

How many pages and Line Items can Xtracta process?

Frequently Asked Questions

Parameter	Required	Value	Description
`login_token`	⚠️	`{string}`	A current login token. Supply this by itself, or use `emailaddress` and `password` instead.
`emailaddress`	⚠️	`{email}`	The user's email address. Required when `login_token` is not supplied.
`password`	⚠️	`{string}`	The user's password. Required with `emailaddress` when `login_token` is not supplied.

Element	Description
`<status>`	The response status code.
`<message>`	Human-readable information about the operation.
`<user_id>`	The authenticated user's ID.
`<user_name>`	The authenticated user's name.
`<api_key>`	The API key assigned to the authenticated user.

Status	Message	Description
`401`	Invalid authentication information	Supply a valid login token, or a valid email address and password.
`401`	Login token is expired	Request a new login token and retry.
`500`	multiple application for user(...) found	The user has an ambiguous API-application mapping. Contact support.
`500`	Internal server error occurred. Please try again later or contact support@xtracta.com	Retry and contact support with the request parameters and timestamp if it persists.

Authorize (Get user API key)

POST Parameters

Code Examples

Sample Request

Sample Response

Schema Definition

Response Elements

Error Responses

Was this page helpful?