# Authentication

The Ringtime API uses an organization API key.

## Get a key

Send an email to [success@ringtime.ai](mailto:success@ringtime.ai). Name your
organization and the system that will call the API. Ringtime issues the key and
sends it to you. There is no self-service page.

## Send the key

Put the key in the `Authorization` header, with the `Bearer` prefix.

```http
Authorization: Bearer <your-api-key>
```

Example. `test_mode: true` keeps the call on the number in `contact`, so use
your own number while you try the key.

```bash
curl -X POST https://api.ringtime.ai/api/v2/triggers \
  -H "Authorization: Bearer $RINGTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": "warehouse-nl",
    "contact": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15555550100",
      "email": "example@example.com",
      "language": "nl"
    },
    "test_mode": true
  }'
```

## What the key gives you

The key identifies your organization. It does not identify a person. Ringtime
reads the organization from the key, so you never send an organization id in the
request.

Each endpoint decides which credentials it accepts. Not all endpoints accept an
organization key. The [API reference](/api) shows the accepted security scheme
for each operation.

## Keep the key safe

- Store the key in a secret store. Do not put it in source code.
- Send it only over HTTPS.
- Use one key for each integration. This makes it easy to replace one key.
- Email [success@ringtime.ai](mailto:success@ringtime.ai) immediately if a key leaks. Ringtime replaces it.

## Errors

A missing or bad key gives HTTP 401. A valid key without the necessary rights
gives HTTP 403. Read [Errors](/errors) for the response shape.