---
title: "Authentication"
description: "Two ways to authenticate with the OnePageCRM REST API — HTTP Basic with your API key, or OAuth 2.1 Bearer tokens."
canonical_url: https://developer.onepagecrm.com/api/authentication/
source: Markdown mirror of https://developer.onepagecrm.com/api/authentication/
---

Every request to the REST API must be authenticated. The base URL is:

```
https://app.onepagecrm.com/api/v3
```

There are two ways to authenticate. Pick the one that matches what
you're building:

| Method | Best for |
| --- | --- |
| [HTTP Basic](#http-basic-auth) | Scripts, internal tools, accessing your own account |
| [OAuth 2.1](#oauth-21) | Apps acting on behalf of other OnePageCRM users |

## HTTP Basic auth

The simplest path. Sign in to OnePageCRM and open the
[API settings page](https://app.onepagecrm.com/app/api), then open the
**Configuration** tab. You need two values:

| Value | Used as |
| --- | --- |
| `user_id` | HTTP Basic username |
| `api_key` | HTTP Basic password |

Pass them with every request:

```bash
curl -u "USER_ID:API_KEY" \
  https://app.onepagecrm.com/api/v3/contacts.json
```

That's it. If this is your first call, the
[quickstart](/getting-started/quickstart/) walks you through the
response envelope and a few useful endpoints.

Treat the `api_key` like a password. It grants full access to your
account. Keep it in an environment variable or a secrets manager —
never in source control.

## OAuth 2.1

> **OAuth is in closed beta.** Client registration is currently handled
> by the OnePageCRM team — [request access](/oauth/registration/). You
> can build against your own account with
> [HTTP Basic](#http-basic-auth) in the meantime.

If your app acts on behalf of other OnePageCRM users, use
[OAuth 2.1](/oauth/overview/). Your app never sees the user's API key —
it gets an access token from the OnePageCRM authorization server and
sends it as a Bearer header:

```bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://app.onepagecrm.com/api/v3/contacts.json
```

The token response includes an `aud` field — the base URL of the
user's CRM API. Build your API URLs from it rather than hard-coding
`app.onepagecrm.com`. The [OAuth reference](/oauth/reference/) covers
the full token response.

### Scopes

Scope is enforced per endpoint:

| Endpoint type | Accepted scopes |
| --- | --- |
| Read (GET) | `crm` or `crm.readonly` |
| Write (POST, PUT, DELETE) | `crm` |

A `crm.readonly` token attempting a write gets `403` with the message
`Insufficient OAuth scope. Required: crm`.

### OAuth endpoint coverage

Nearly all endpoints accept OAuth tokens. A few are API-key only —
chiefly `GET /bootstrap`; fetch the individual reference
endpoints (`statuses`, `pipelines`, `custom_fields`, ...) instead. An
API-key-only endpoint answers an OAuth token with `403` and the
message `This endpoint is not available for OAuth applications`.

## Security notes

- **Treat the `api_key` as a password.** It grants full access to the
  account. Store it in environment variables, not code.
- **Use OAuth for anything user-facing.** Never ask another user to
  hand you their API key — [OAuth 2.1](/oauth/overview/) exists so they
  don't have to.
- **Always use HTTPS.** The API is only served over HTTPS; never log or
  cache credentials in plaintext.

## What to read next

- **[Quickstart](/getting-started/quickstart/)** — make your first call in under five minutes.
- **[Errors](/api/errors/)** — the response envelope and every error code.
- **[API reference](/api/reference/)** — every endpoint, parameter, and response shape.