How do Plugsky API keys, scopes and roles work?

Key facts

Key format	sk-live-… project-scoped, hashed at rest with Argon2id and never logged
Base URL	https://api.plugsky.com/v1
Roles	read lists models/usage/audit; infer runs chat, embeddings and batch; admin adds key, billing and RBAC management
Scopes	Comma-separated per key, e.g. chat:write,embeddings:write,files:read
Rotation	Old keys stay valid for 24 hours after rotation for zero-downtime deploys
Free plan keys	2 API keys with the two free models, no card required
OAuth	Authorization-code flow with PKCE for SaaS apps acting for users
Product status	Keys, scopes and roles are live; free models are chat and JSON only

TL;DR

• One header authenticates everything: Authorization: Bearer sk-live-….
• Keys are project-scoped and role-scoped — treat each service as its own identity.
• Grant the narrowest scope list that works and keep admin keys out of servers.
• Rotate quarterly; the 24-hour overlap makes rollouts boring.
• Use read keys for dashboards and monitoring, never infer keys in the browser.

How it works, step by step

1. Create a project in the dashboard and generate a key under API keys.
2. Assign the narrowest role: read for observability, infer for inference services.
3. Trim scopes to exactly what the service calls, for example chat:write.
4. Store the key in an environment variable or secret manager — never in source control.
5. Verify the key with GET /v1/models before wiring it into an application.
6. Rotate quarterly and confirm the old key fails after the 24-hour overlap.
7. Alert on 401, 403 and 429 responses per key so leaks and misconfiguration surface early.

Original data

Try it yourself

Open the OpenAI-compatible API tester →

Key anatomy and authentication

Every request carries one header. The key itself encodes the environment (sk-live-) and resolves server-side to a project, a role and a scope list:

curl https://api.plugsky.com/v1/models \
  -H "Authorization: Bearer $PLUGSKY_API_KEY"

SDKs read the same value from configuration, so an OpenAI-compatible client needs only the base URL and the key. Keys are hashed at rest with Argon2id and excluded from request logs, which means a leak is a rotation event, not a search problem.

Roles versus scopes

A role is a coarse permission bundle; scopes are the fine-grained list attached to the key. The built-in roles are read (list models, fetch usage, view audit logs), infer (chat, embeddings, image, audio and batch inference) and admin (adds key management, billing and RBAC).

• One key per service — a billing worker and a support bot deserve separate identities.
• One key per environment — staging keys never touch production data.
• Scopes as guardrails — a key with only embeddings:write cannot accidentally spend chat capacity.
• Admin stays human — admin keys belong in the dashboard, not in a server's .env file.

Rotation without downtime

Rotation is designed to be routine. Generate the replacement key, write it to your secret manager (Vault, AWS Secrets Manager, GCP Secret Manager or Azure Key Vault), and let workers pick it up. The old key remains valid for 24 hours after rotation, so a rolling deploy never hits a window where every instance holds a dead credential.

1. Create the new key with the same role and scopes.
2. Update the secret and restart consumers.
3. Confirm traffic on the new key in usage analytics.
4. Let the 24-hour overlap expire and delete the old key.

Key creation, scope changes, rotation and deletion are written to the audit log with actor, timestamp and IP.

Common mistakes

• Shipping keys to browsers. Browser code exposes credentials; proxy through your server or an edge function with a secret.
• One key for every service. Revoking it becomes an outage instead of a single-service action.
• Over-scoping to save time. Adding files:read because it might be useful widens the blast radius for no benefit.
• Forgetting deprovisioning. Tie key ownership to a person or service and remove keys when the work ends.
• Ignoring 403s. A scope error in logs usually means a config drift between environments.

Honest comparison

Capability	Plugsky	Typical API key model	Rolling your own
Key format	sk-live-… project-scoped with role and scopes	Usually one long-lived token	Self-issued credentials
Permissions	read / infer / admin plus per-key scopes	Often all-or-nothing	You build RBAC
Rotation	24-hour overlap, no downtime	Manual swap	Custom automation
OAuth for SaaS	Authorization code with PKCE	Rarely offered	You implement it
Audit trail	Create, rotate, scope and delete events logged	Varies	Custom logging
Integration effort	One header	One header	Weeks of work

Frequently asked questions

What does a Plugsky API key look like?

It is a bearer token prefixed sk-live- and scoped to one project. Send it as Authorization: Bearer sk-live-… on every request to https://api.plugsky.com/v1.

What are the three built-in roles?

read lists models, usage and audit logs; infer runs chat, embeddings and other inference; admin adds key management, billing and RBAC. Production services should use infer at most.

How do scopes differ from roles?

A role is a built-in permission bundle; scopes are the comma-separated fine-grained list on the key, such as chat:write or embeddings:write. The effective permission is the intersection.

How does key rotation work?

Generate a replacement, deploy it, and the old key stays valid for 24 hours after rotation. That overlap lets rolling deployments finish before the old credential stops working.

How many API keys does the free plan include?

The free plan includes two API keys and two free AI models (plugsky-micro and plugsky-lite) with no credit card. See the live pricing page for current plan details.

Should I put an API key in a mobile or web client?

No. Keys are bearer credentials; anyone who can read them can spend your capacity. Call Plugsky from your backend or a server-side edge function.

Does Plugsky support OAuth for third-party apps?

Yes. The OAuth 2.0 authorization-code flow with PKCE is documented for SaaS apps that act on behalf of a user's workspace.

What happens if a key leaks?

Rotate it immediately. Scoped, per-service keys limit the blast radius, and the audit log shows usage by key while rate limits contain the damage.