Authentication

Every API request is made as one of your supporters, and proves it with an API token. For your own scripts and integrations, use a personal API token: you make it in a few seconds, choose what it may do and when it expires, and can revoke it at any time.

Building an application that other people will connect to their Tender accounts? Use OAuth instead, so each person approves it and you never handle their tokens by hand.

Make a personal API token

Only support staff can make tokens, because only support staff can use the API.

1. Log in to your Tender site, click your name at the top of the page, then Account settings.
   
2. Under API keys, click Manage your API tokens. (The page's address is https://yoursite.tenderapp.com/profile/api_tokens.)
   
3. Under Create a token, fill in:
   
   • Name: what the token is for, such as "Billing sync". It helps you tell your tokens apart later.
   • Access: Read only or Read and write.
   • Expires: in 7, 30, 90 or 365 days. 90 days is the default.
4. Click Create token.

Your new token appears at the top of the page. Copy it now: it's shown only once. Tender keeps only a fingerprint of it, so nobody (us included) can show it to you again. If you lose it, revoke it and make another.

Personal tokens start with tender_pat_. You can have up to 20 active tokens at a time.

Use the token

Send the token in the Authorization header of every request, after the word Bearer:

curl -H "Accept: application/vnd.tender-v1+json" \
     -H "Authorization: Bearer $TENDER_TOKEN" \
     https://api.tenderapp.com/yoursite/discussions

The token works on the site you made it on, as you: the API sees and does what you can in Tender.

Read only or read and write

• A Read only token can make GET (and HEAD) requests: list and read things.
• A Read and write token can also create, change and delete them (POST, PUT, DELETE).

A read-only token that tries to change something gets 403 Forbidden:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="Tender", resource_metadata="https://api.tenderapp.com/.well-known/oauth-protected-resource/yoursite", scope="write", error="insufficient_scope"

This API token doesn't have the write scope.

Choose Read only whenever your integration only needs to look: reports, dashboards, exports.

Expiry and revoking

A token stops working when it expires. Tender doesn't renew tokens: before one expires, make a new one, put it in your integration, and revoke the old one.

The Your tokens table on the API tokens page lists your active tokens, with the end of each one (such as tender_pat_…x7Qa), its access, when it was created, when it was last used and when it expires. Click Revoke next to a token to stop it working straight away.

A token also stops working if you leave your site's support staff or your account is disabled.

When a token is refused

A request without a valid token gets 401 Unauthorized, and the WWW-Authenticate header says why.

No token at all:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Tender", resource_metadata="https://api.tenderapp.com/.well-known/oauth-protected-resource/yoursite", scope="read write"

A token that's wrong, revoked, or for another site:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Tender", resource_metadata="https://api.tenderapp.com/.well-known/oauth-protected-resource/yoursite", scope="read write", error="invalid_token"

An expired token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Tender", resource_metadata="https://api.tenderapp.com/.well-known/oauth-protected-resource/yoursite", scope="read write", error="invalid_token", error_description="The token has expired"

Your API token has expired. Create a new one on your Tender profile's API tokens page.

A valid token whose owner isn't on your support staff gets 403 Forbidden ("API access is limited to your site's support staff").

(resource_metadata is for OAuth applications, which use it to find out how to sign in: see OAuth for applications.)

Keep tokens safe

A token works like your password for the API.

• Make one token per integration, so you can revoke one without breaking the others.
• Give it the least it needs: read only if it only reads, and the shortest expiry you can live with.
• Keep it out of code and URLs. Put it in an environment variable or your platform's secret store, never in a repository, a web page or a query string.
• Revoke it as soon as it might have leaked, then make a new one. Tokens start with tender_pat_, which makes a leaked one easy to recognise, for you or for a secret scanner you configure.
• Check Last used now and then, and revoke tokens nothing uses any more.

Other ways in

• Single sign-on (multipass) logs your customers in to your site; it's described in its own article and isn't how you use the API.
• Integrations made before personal tokens: see What's new in Tender.