---
title: "Authentication"
description: "Authenticate API requests with an API key using HTTP Basic authentication."
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.touchsms.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

Every API request needs an API key. Keys are sent with [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over HTTPS.

## Create an API key

1. Sign in to [touchSMS](https://app.touchsms.com.au).
2. Open **Settings** in the sidebar, then **API Keys**.
3. Click **Create API Key** and enter a name for the key.

Each key has two parts:

| Part | Used as |
|---|---|
| Access Token | Basic auth **username** |
| Token ID | Basic auth **password** |

The API Keys page labels them the same way. Create a separate key for each integration so you can disable one without affecting the others.

## Send the credentials

Most HTTP clients take a username and password and build the header for you:

```sh
curl -u "ACCESS_TOKEN:TOKEN_ID" https://app.touchsms.com.au/api/v2/account
```

If yours doesn't, send the header yourself. `<credentials>` is the Base64 encoding of the Access Token and Token ID joined by a single colon:

```
Authorization: Basic <credentials>
```

For example, in PHP:

```php
$header = 'Authorization: Basic ' . base64_encode($accessToken . ':' . $tokenId);
```

Or in Node.js:

```js
const header = 'Basic ' + Buffer.from(`${accessToken}:${tokenId}`).toString('base64');
```

All requests must use HTTPS.

## Authentication errors

A missing, malformed, invalid or disabled key returns `401 Unauthorized`:

```json
{
  "message": "Unauthenticated."
}
```

Send `Accept: application/json` with every request so errors always come back as JSON.

## Test with the OpenAPI spec

The OpenAPI spec for this API is at [`/api/openapi.json`](/api/openapi.json). Import it into Postman, Insomnia or another API client, set Basic auth with your Access Token as the username and Token ID as the password, and every endpoint is ready to try.

## Keep keys safe

Anyone with a key can send messages on your account. Keep keys on your server, never in browser or mobile app code, and disable a key from the API Keys page if it leaks. See [Security](/concepts/security/).

Source: https://dev.touchsms.com.au/get-started/authentication/index.mdx