How does Plugsky API authentication work?

Key facts

Chat endpoint	POST https://api.plugsky.com/v1/chat/completions
Authentication header	Authorization: Bearer sk-live-… (project-scoped key)
Key roles	read (list models, usage, audit), infer (chat, embeddings), admin (keys, billing, RBAC)
Scopes	Comma-separated per key, e.g. chat:write,embeddings:write,files:read
Rotation window	Old keys remain valid for 24 hours after rotation
Auth errors	401 invalid or missing key; 403 missing scope; 429 rate limit with Retry-After
OAuth	OAuth 2.0 authorization-code flow with PKCE for SaaS apps acting for users
Product status	Live (chat, streaming, embeddings); audio, images, batch and fine-tuning are coming soon

TL;DR

• Every call needs one header: Authorization: Bearer sk-live-….
• Keys are project-scoped and role-scoped, and one key reaches 30+ models.
• Rotate quarterly — old keys stay valid for 24 hours so rollouts do not brown out.
• 401 means the key is wrong; 403 means it lacks a scope; 429 returns Retry-After.
• OAuth 2.0 with PKCE exists for SaaS apps that act on a user's workspace.

How it works, step by step

1. Create a project in the Plugsky dashboard and generate an API key (free plan, no card).
2. Store the key in an environment variable such as PLUGSKY_API_KEY — never in source control.
3. Send Authorization: Bearer $PLUGSKY_API_KEY with the base URL https://api.plugsky.com/v1.
4. Grant the narrowest scopes that work (chat:write for inference, embeddings:write for vectors).
5. Verify the key with GET /v1/models, then run one chat completion.
6. Rotate quarterly and confirm old keys stop working after the 24-hour overlap.
7. Monitor 401, 403 and 429 responses and wire alerts into your logs.

Original data

Try it yourself

Open the OpenAI-compatible API tester →

The bearer-token model

Every Plugsky request is authenticated with a bearer token. Keys are created in the dashboard, scoped to one project, and prefixed sk-live-. The header is identical for chat, embeddings and model listing:

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

The SDKs read the same key from configuration, so an OpenAI-compatible client needs only the base URL and key:

from openai import OpenAI
client = OpenAI(api_key="sk-live-…", base_url="https://api.plugsky.com/v1")

Keys are hashed at rest with Argon2id and are never written to request logs, so treat any leak as a rotation event rather than a forensic hunt.

Roles, scopes and least privilege

Plugsky has three built-in roles. read can list models, fetch usage and view audit logs. infer can run chat, embeddings, image, audio and batch inference. admin adds key management, billing and RBAC.

• Use one key per service: a billing worker and a support bot should not share credentials.
• Use one key per environment: staging keys never touch production data.
• Keep admin out of production: admin keys belong in the dashboard, not in .env files on servers.
• Scope narrowly: chat:write,embeddings:write for an inference service; add files:read only when needed.

Scopes are comma-separated on each key, so a key that only writes embeddings cannot accidentally spend your chat quota.

Rotation, revocation and zero-downtime deploys

Rotation is designed to be boring. When you rotate a key, the old key stays valid for 24 hours, which gives rolling deployments time to pick up the new secret without a brownout. The workflow:

1. Generate the replacement key in the dashboard.
2. Write it to your secret manager (Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault).
3. Restart or redeploy workers so they read the new value.
4. Confirm traffic uses the new key in usage analytics, then let the 24-hour window expire.

Every create, rotate, scope-change and delete action is written to the audit log with actor, timestamp, IP and a request-body hash, which maps cleanly to SOC 2 and internal access reviews.

Debugging authentication failures

Errors follow the OpenAI schema: {"error":{"message","type","code","param"}}. Start with the status code:

• 401: the header is missing or malformed. Check for a stray space, a placeholder key, or an environment variable that never loaded.
• 403: the key is valid but lacks the required scope. Compare the key's scope list with the endpoint you are calling.
• 429: the key works, but you hit the fair-use request rate. Honor the Retry-After header; the SDKs back off automatically.
• 409: an Idempotency-Key was reused with a different body. Generate a fresh key per logical request.

To see the exact response, run curl -i against a minimal request before reaching for the SDK, then reproduce in the API tester.

Honest comparison

Capability	Plugsky	Typical AI API key	Rolling your own auth
Key format	sk-live-… project-scoped	Single long-lived token	Self-issued credentials
Roles and scopes	read / infer / admin plus per-key scopes	Usually all-or-nothing	Build it yourself
Rotation	24-hour overlap, no downtime	Manual swap	Custom automation
OAuth for SaaS	Authorization code + PKCE	Rarely offered	You implement it
Audit trail	Key create, rotate and scope events logged	Varies by provider	Custom logging
Integration effort	One header	One header	Weeks of work

Frequently asked questions

What header does Plugsky use for authentication?

Send Authorization: Bearer sk-live-… on every request. The same key works for chat completions, embeddings and model listing.

Where do I create an API key?

In the Plugsky dashboard under API keys. The free plan includes two API keys and two free models with no credit card.

What is the difference between a role and a scope?

A role is a built-in permission bundle (read, infer, admin); scopes are fine-grained permissions attached to a key, such as chat:write or embeddings:write.

Can I use one key for everything?

You can if it holds every scope, but separate keys per service and environment make revocation and audit far easier. Keep admin keys out of production.

What happens to the old key after rotation?

It stays valid for 24 hours after rotation so rolling deployments do not fail, then it stops working.

Which errors mean an auth problem?

401 means missing or invalid key, 403 means the key lacks the required scope, and 429 means you hit the fair-use rate limit — honor the Retry-After header.

Does Plugsky support OAuth for third-party apps?

Yes, OAuth 2.0 authorization code flow with PKCE is supported for SaaS apps that act on behalf of a user's workspace. See the OAuth guide in the docs.

Are API keys safe to use in the browser?

No. Browser code exposes keys. Call Plugsky from your server, an edge function with a server-side secret, or a backend-for-frontend proxy.