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

# Authentication

> API keys, the tokens they're exchanged for, and what each key can do.

Your system signs in with an **API key**: a key id (`mk_…`) and a secret (`ms_…`). It exchanges them for an **access
token**, and sends that token with every request.

## Create an API key

1. In the portal, open **Settings → API keys**. Only Owners and Admins see it.
2. Give the key a name that says which system uses it, such as `QuickBooks sync`.
3. Under **What it can do**, tick only what that system needs ([permissions](#permissions)).
4. Select **Create key**, then copy the key id and the secret. **The secret is shown once.** Mojo Payments keeps only a
   fingerprint of it, so a lost secret can't be recovered: create a new key and revoke the old one.

An API key belongs to your organization, not to the person who made it: it keeps working when they leave.

<Warning>
  Treat the secret like a password. Keep it in your system's secret store, never in code, a URL, an email or a log.
</Warning>

## Get an access token

Send the key to `POST /oauth/token` (the OAuth 2.0 client credentials grant):

```bash theme={null}
curl https://api.paymentsmojo.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=mk_0123456789abcdef0123 \
  -d client_secret=ms_…
```

The body can also be JSON, or the key id and secret can go in an HTTP Basic `Authorization` header, as OAuth client
libraries send them.

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "payments.create payments.view",
  "organization_id": "0b8f2d4e-5c1a-4e7b-9a63-2f1d8c4e7a90"
}
```

* The token lasts **10 minutes** (`expires_in`, in seconds). Keep using it until it expires, then get a new one; don't
  get a new token for every request.
* `scope` lists what the key can do. `organization_id` is your organization's id.

## Use the token

```bash theme={null}
curl https://api.paymentsmojo.com/deposits -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs…"
```

## Permissions

A key can do only what was ticked when it was made. A request for anything else gets `403`.

| Permission | In the portal | Lets the key |
| - | - | - |
| `payments.view` | Read invoices, card payments and deposits | List and read invoices, deposits and card payments |
| `payments.create` | Create, send and cancel invoices… | Create, send and cancel invoices, and remove customers' saved cards |
| `locations.view` | Read locations | List and read locations |
| `accounts.view` | Read MIDs (merchant accounts) | List MIDs |
| `portfolio.view` | Read the merchants in your portfolio… | Resellers: list the merchants in the portfolio |
| `applications.view` | Read merchant applications submitted through you | Resellers: list and read those applications |

You can give a key only what you can do yourself across the whole organization. Merchant permissions appear for
merchants and reseller permissions for reseller partners.

## Revoke a key

In **Settings → API keys**, select **Revoke**. New tokens are refused at once, and tokens already issued stop working
within a minute (`401` with the title `API key revoked`). Revoked keys stay in the list, marked with the date.

## Token errors

| Answer | Means |
| - | - |
| `401` `invalid_client` | Unknown key id, the wrong secret, a revoked key, or a suspended organization. |
| `400` `unsupported_grant_type` | Use `grant_type=client_credentials`. |
| `400` `invalid_request` | The key id and secret weren't sent. |
| `429` | More than 30 token requests a minute from one address. Reuse tokens until they expire. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.