Tokens and access

How to decide who may call a service: public or token-protected, creating and revoking tokens, where a caller puts the token, and what an expired or wrong token answers.

1:05

Public or protected

A published service is in one of two states:

• Public: anyone who knows the address can call it. No token is needed.
• Token-protected: every call must carry a valid token of this service.

There is no separate switch. The tokens decide: a service with at least one token is protected, a service without tokens is public.

In both cases callers only send inputs and get outputs. They never see the workbook or its formulas.

Create a token

Tokens are managed on the service page under API → Access (Zugriff). The service must be published for the API tab to open.

1. Open API → Access.
2. Click Create Token (Token erstellen).
3. Enter a Token Name (Token-Name), for example the system or customer that will use it. Description is optional.
4. Optional: set Expiration (Optional) (Ablaufdatum) to a date and time after which the token stops working.
5. Click Create Token.
6. The window Token Created Successfully shows the token. Copy it now and store it in a safe place.
7. Click Done (Fertig).

The token is shown once, when it is created. It cannot be displayed again afterwards. If it is lost, create a new token and revoke the old one.

Creating the first token protects the service at once, without saving or republishing. The app confirms this with "Token authentication has been automatically enabled". From that moment calls without a token are refused.

The token list

API → Access lists every token of the service:

• Name: the name you gave it.
• Usage (Nutzung): how many calls were made with it. A call is a calculation, refused ones included, the same calls the Usage tab counts for this token. Requests that calculate nothing, such as an AI assistant connecting or reading the list of tools, are not counted.
• Created: the day it was created.
• Expires: the expiry date, Never (Nie) or Expired (Abgelaufen).

Give each calling system its own token. Then the list and the Usage tab show who calls, and you can revoke one caller without touching the others.

Revoke a token

1. Click the bin icon in the row of the token.
2. Confirm Revoke this token? with Revoke (Widerrufen). This cannot be undone.

The token stops working at once. Calls with it answer "Invalid token". For 30 days the Usage tab lists such calls under the token's name with "(revoked)", so you see whether a client still uses it.

Revoking the last token removes the token requirement, and the service is public again immediately. While exactly one token is left, the page warns about this. To keep the service protected while you replace a token, create the new token first, then revoke the old one.

Where the token goes

curl -X POST "https://spreadapi.io/api/v1/services/{serviceId}/execute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"inputs": {"amount": 20000, "rate": 0.05}}'

https://spreadapi.io/api/v1/services/{serviceId}/execute?amount=20000&rate=0.05&token=YOUR_TOKEN_HERE

A token in the address is convenient for Excel and Google Sheets, but an address is easily shared or logged. Prefer the header wherever your tool can set one.

Keep tokens safe

• A token is a password for the service. Do not put it into a public web page, a public repository or a shared document.
• For calls from a website, keep the token on your server; see Calling from a web page.
• Set an expiry for tokens you hand out for a limited time.
• Revoke a token as soon as you suspect it leaked.

When the token is refused

A token-protected service answers HTTP 400 when the token is missing or not accepted. The text in error says which case it is:

The status is 400 by design, not 401. Check the text in error. What to do in each case is in Token errors.

Other ways to reach the service

A token of the service also works for batch calls, the OpenAPI file and the discovery address. How other people's AI assistants reach a protected service is in The MCP address of a service. AI assistants connected to your own account reach your services through that connection, without a service token; see The AI agents page. The web app has its own access rules; see App access and tokens.

Related

• Call a service over the API
• Security overview
• Usage overview

For developers and agents

• Token format: a text starting with svc_tk_. A token belongs to exactly one service.
• Accepted on execute: Authorization: Bearer <token> (GET and POST), ?token=<token> (GET), or a "token" field in the POST body, as API → Test sends it.
• Batch calls read the token from the "token" field of the body; see Batch calls.
• A refused token answers 400 on the execute address with {"error": "...", "message": "...", "serviceId": "...", "inputs": {...}, "details": null}.
• The OpenAPI file of a protected service answers 401 without a valid token. The discovery address answers 401 as well.
• A public service ignores a token that is sent.
• There is no call to list or create tokens with a service token; tokens are managed by the owner under API → Access.

FAQ

How do I protect my API with a token?

Open API → Access and click Create Token. The first token protects the service at once; every call then needs a valid token.

Where do I put the token in my request?

Send the header Authorization: Bearer <token>. On GET you can also add ?token=<token> to the address.

I lost my token. Can I see it again?

No. A token is shown once, when it is created. Create a new token, switch your callers to it and revoke the old one.

How do I make my service public again?

Revoke all tokens under API → Access. When the last token is revoked, the service is public again immediately.

Why does a call without a token answer 400 and not 401?

That is how the execute address is designed: token problems answer HTTP 400, and error says what is wrong, for example "Invalid token". Check the text, not only the status.

Can I set an expiry date for a token?

Yes, when you create it, under Expiration (Optional). After that date and time, calls with it answer "Token expired"; the date cannot be changed later, so create a new token instead.

Can one token be used for several services?

No. A token belongs to one service; on another service it answers "Token does not belong to this service".

How do I replace a token without downtime?

Create a new token, move your callers to it, then revoke the old one. Creating before revoking also keeps the service protected the whole time.

As an agent, what do I do when I get "Authentication required"?

The service is token-protected and your call carried no token. Ask the owner for a token of this service and send it as Authorization: Bearer <token>; do not retry without it.

Do I have to republish after creating or revoking a token?

No. Token changes apply to the live service at once.

Can I see which token made how many calls?

Yes. API → Access shows the calls per token, and the Usage tab shows who calls by token name; see Usage overview.