Get started
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, 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 onapi.sandbox.charitips.comonly,live_credentials onapi.charitips.comonly.- 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.
Create an access token
Send your client id and secret as Basic authentication. The response holds the accessToken and your accountId.
curl -X POST https://api.sandbox.charitips.com/v1/authentication \ -u "$CHARITIPS_CLIENT_ID:$CHARITIPS_CLIENT_SECRET"Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.
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:
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.
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 with the
accountIdwhose data the widget shows, yours or a child account's. See Admin widgets. - Authenticated donor widgets: Create a donor widget token with the
donorId. It needs the B2C use case on your plan,402 Plan upgrade requiredotherwise. See Donor widgets.
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.
curl -X POST https://api.sandbox.charitips.com/v1/authentication/widget \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "accountId": "<accountId>" }'Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.
Open the dashboard without a second login
Create a user magic link 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.
Related
Your first donation, Sandbox, Troubleshooting, Create a token.