An API key is a credential for server-to-server integrations with no user involved. Use one for nightly batch jobs, syncing data with your HR system, feeding a BI tool and similar work.
App tokens vs. API keys
| App token (OAuth) | API key | |
|---|---|---|
| Acts as | The user who signed in | The organization itself (not tied to any person) |
| What it's allowed to do | Scopes allowed for the app ∩ scopes requested ∩ the user's own permissions | Exactly the scopes set on the key |
| Best for | Mobile apps, screens in an internal portal | Batch jobs, system integrations, scheduled runs |
| Expiry | Access token lasts up to 24 hours (can be refreshed) | Valid until you revoke it (you can also set an expiry date) |
write:members can change members without anyone's permissions standing in the way.
Where not to use API keys
Issuing a key
API keys are issued per organization. Developers and organization admins can issue them.
When you issue a key, you decide three things:
- Name (名前) — so you can tell what the key is for. For example, "HR system nightly sync" or "BI integration (production)".
- Scopes (スコープ) — what the key is allowed to do. See Choosing scopes for details.
- Expiry date (optional) (有効期限（任意）) — the key works until 23:59 Japan time (JST) on that date, and the list shows the date in Japan time. Leave it blank and the key stays valid until you revoke it.
Using a key
You can send it in either of these forms:
X-Api-Key: mnb_live_…
Authorization: Bearer mnb_live_…
Because every key starts with the mnb_live_ prefix, you can tell at a glance that a string you find in a log or a paste is a Manabu2 API key.
Storing and rotating keys
- Keep keys in your cloud provider's secret management service
- Load them as environment variables at runtime
- Use a separate key for each purpose (if one leaks, you can contain the damage)
- Use different keys for production and testing
- Write keys directly into source code
- Commit config files containing keys to Git
- Share keys over chat or email
- Reuse one key across several systems
If you suspect a key has leaked
- Revoke the key right away
- Issue a new key and update the settings in the connected system
- Check for any suspicious API calls
Revocation takes effect immediately; there's no need to wait for the key to expire. If you keep separate keys for each purpose, only one system stops working while you do this.
Rate limits
The API limits how often you can call it. Authenticated calls are limited to 300 per minute. If you go over the limit, you get a 429 response, and the Retry-After header tells you how many seconds to wait. See the API documentation for details.
