# Authentication

> Create an API key and send it in the X-API-Key header with every request.

Section: Get started · Last updated: 2026-11-18

You authenticate every request with an API key. This guide shows how to create a key, how to send
it, and what to do when it stops working. You need a Transferz staging account.

## How authentication works

The Partners API and the Transfer Companies API take your API key in the `X-API-Key` header.

An API key belongs to a user, not to a company. A call made with your key can do what your account
can do, for the companies your account can access.

## Create an API key

1. [Sign in](https://developers.test.transferz.com/sign-in) to the portal and open the [workspace](https://developers.test.transferz.com/workspace).
2. Create a key and give it a description that says where you use it, such as "Booking service on
   staging".
3. Copy the key and store it in your secret store. The key is shown only once. Transferz keeps only
   a hash of it, so nobody can show it to you again.

If you lose a key, delete it in the workspace and create a new one.

> **What to know about keys:**
>
> - A key is a string of 24 letters and digits.
> - A key expires three months after it was **last used**. A key that you use regularly does not
>   expire.
> - Each user can have at most 100 active keys. Creating more fails with `403` and the code
>   `API_KEY_LIMIT_REACHED`; delete keys you no longer use.
> - Staging keys do not work in production. Transferz gives you production credentials when you go live.

## Send the key

Add the `X-API-Key` header to every request to the Partners API or the Transfer Companies API:

**Request:** [`GET /journeys`](https://developers.test.transferz.com/reference/transfer-companies/search-journeys)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=10' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=10", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=10"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=10");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys?page=0&size=10');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

A request without the header, or with a key that is wrong, deleted or expired, gets `401`.

Keep keys out of source code, logs, browser code and mobile apps. Call the API from your server.

## Errors

| Status | Cause                                                       | What to do                                                                |
| ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
| `401`  | Missing, wrong, deleted or expired key.                     | Check the header name and value. Create a new key if the old one expired. |
| `403`  | Your account may not do this, or you reached the key limit. | Check the account and the company. Delete unused keys.                    |

More in [Errors](https://developers.test.transferz.com/guides/essentials/errors).

## Related

### Walk-through steps

- [Partner: connect](https://developers.test.transferz.com/walkthrough/partner/connect)
- [Transfer company: connect](https://developers.test.transferz.com/walkthrough/transfer-company/connect)
