Every call to your Goosy Bear account carries an API key as a bearer token:
There is one kind of credential. The same key works for direct API calls and
for AI assistants that connect to your account.
Creating a key
Keys are created in the app, under Settings → API & MCP. You need
permission to use the API; if the page is not there, see
Who can use the API.
The key is displayed once, when you create it. We store only a fingerprint
of it, so we cannot show it to you again or recover it for you. Copy it into a
password manager or secret store immediately.
Choosing an expiry
The dialog offers Never expires (the default), 30 days, 90 days, or a date
you pick. Never expires is the right choice for something you run
continuously; a dated key is the right choice for a trial, a contractor, or a
one-off migration, because it closes itself if you forget it.
What a key can do
A key acts as you. It carries the permissions of the person who created it,
checked on every single call. So:
- A key can never do more than you can do in the app.
- If your permissions change, the key’s reach changes with them on the very
next call. Nothing is frozen at the moment the key was made.
- Revoking a key stops it immediately. Your other keys keep working.
You can optionally narrow a key to a single workspace when you create it. A key
without that narrowing reaches every workspace you have access to.
Choosing a workspace
Your account is fixed by the key. If you have more than one workspace, tell us
which one a call is for — either by narrowing the key when you create it, or by
naming the workspace on the call. A request we cannot place in one workspace is
refused rather than guessed at.
Assistants show which workspace they are working in, so you can see it before
you ask for anything.
Keys for integrations
Do not put a personal key into a shared system. If someone leaves and their
access is removed, every integration riding on their key stops with them.
For anything shared — a scheduled job, an internal tool, another platform —
an owner can create a service account: an identity that belongs to the
account rather than to a person, with its own permissions and its own keys. An
owner sets one up; from then on you mint its keys on the API & MCP page,
where they are listed alongside everyone else’s.
Keeping keys safe
- Store keys in a secret manager or environment variable, never in source code,
a shared document, or a chat message.
- Use one key per place you use it. Then revoking one thing does not break
everything else.
- Set an expiry date on keys you only need for a while.
- Rotate on any suspicion: create the new key, switch over, then revoke the old
one — in that order, so nothing goes down in between.
- Revoke a key the moment it is no longer used. The last-used column tells you
which those are.
When something is refused
- Unauthorized — missing, mistyped, revoked, or expired key. All four
answer the same way on purpose, so the endpoint cannot be used to test which
keys exist.
- Not permitted — a valid key, but your permissions do not cover that
action, or someone has switched programmatic access off. The response says
which; Who can use the API explains each case.
- Too many requests — slow down and retry after the period given.
