---
title: "Authentication"
description: "Exchange your client id and secret for an access token, send it as a Bearer token, and create the tokens the widgets and the dashboard links need."
canonical: https://www.charitips.com/docs/get-started/authentication
---

# Authentication

> Exchange your client id and secret for an access token, send it as a Bearer token, and create the tokens the widgets and the dashboard links need.

Every call to the API carries an access token. Your server gets it by sending its client id and secret, keeps it for an hour, and sends it in the `Authorization` header of each call.

> **In short**
>
> - Create a token with [Create a token](https://www.charitips.com/docs/api-reference/create-token.md), your client id and secret sent as Basic authentication.
> - Send it as `Authorization: Bearer <accessToken>` on every other call. It lasts one hour: cache it and create a new one when it expires.
> - `test_` credentials work on `api.sandbox.charitips.com` only, `live_` credentials on `api.charitips.com` only.
> - Your credentials and tokens stay on your server. A widget gets its own token, valid one day, that only opens that widget.

## Your credentials

Create your client id and secret in the dashboard, under Settings, API. They are made for the account you are signed in to, and need API access on your plan. The secret is shown once: store it in your server's secrets, never in a browser, a mobile app or a repository.

Sandbox credentials start with `test_`, live ones with `live_`. Each pair works only on its own environment. See [Sandbox](https://www.charitips.com/docs/get-started/sandbox.md).

## Create an access token

Send your client id and secret as Basic authentication. The response holds the `accessToken` and your `accountId`.

```bash
curl -X POST https://api.sandbox.charitips.com/v1/authentication \
  -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET"
```

The token is valid for one hour. Create it once, keep it in memory or in a shared cache (Redis, for example, in a serverless environment) with an expiry just under the hour, and create a new one when a call answers `401`. Creating a token before each call slows every call down.

- `401 Invalid credentials`: the id or the secret is wrong, or belongs to the other environment.
- `401 Unauthorized`, without a message: the request has no Basic authentication header.
- `403 Account not active`: the account has not finished its onboarding.

## Call the API

Send the token as a Bearer token on every other call:

```bash
curl https://api.sandbox.charitips.com/v1/campaigns \
  -H "Authorization: Bearer $CHARITIPS_TOKEN"
```

With account hierarchy, the same token acts on every child account: pass the child's `accountId`. See [Account hierarchy](https://www.charitips.com/docs/concepts/account-hierarchy.md).

## Tokens for the widgets

A widget runs in your user's browser, so it never gets your access token. Your server creates a token for it, valid one day, which only opens that widget, and passes it to the page.

- **Admin widgets** (campaign metrics, receipts, selection): [Create an admin widget token](https://www.charitips.com/docs/api-reference/create-admin-widget-token.md) with the `accountId` whose data the widget shows, yours or a child account's. See [Admin widgets](https://www.charitips.com/docs/widgets/admin.md).
- **Authenticated donor widgets**: [Create a donor widget token](https://www.charitips.com/docs/api-reference/create-donor-widget-token.md) with the `donorId`. It needs the B2C use case on your plan, `402 Plan upgrade required` otherwise. See [Donor widgets](https://www.charitips.com/docs/widgets/donor.md).

The charity selection widget and the unauthenticated donor widgets need no token: they open with the campaign's `publicKey`. Create a new widget token before the day is over when a page stays open longer.

```bash
curl -X POST https://api.sandbox.charitips.com/v1/authentication/widget \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "<accountId>"
  }'
```

## Open the dashboard without a second login

[Create a user magic link](https://www.charitips.com/docs/api-reference/create-user-magic-link.md) returns a link that signs a dashboard user in. It is valid ten minutes and works once: create it when the user clicks, not in advance. It needs `API` among the account's `authSchemes`, `403 API_AUTH_NOT_ALLOWED` otherwise. See [Dashboards and users](https://www.charitips.com/docs/concepts/account-hierarchy.md#dashboards-and-users).

## Related

[Your first donation](https://www.charitips.com/docs/get-started/first-donation.md), [Sandbox](https://www.charitips.com/docs/get-started/sandbox.md), [Troubleshooting](https://www.charitips.com/docs/api-reference/troubleshooting.md#authentication), [Create a token](https://www.charitips.com/docs/api-reference/create-token.md).