Authentication

Quick Summary: Every request carries Authorization: Bearer sdb_live_.... Keys are created by administrators, scoped per resource, bound to an acting person, rotated with an overlap window, and revoked instantly.

The key

A key looks like sdb_live_ followed by 32 random characters. The prefix identifies the environment that issued the key — production uses sdb_live_, and another environment may issue its own. Only the secret’s length and opacity are guaranteed, so never hard-code or validate the prefix in your client. Send the key on every request:

curl https://prod.skillsdbnext.com/api/v1/careers \
  -H "Authorization: Bearer sdb_live_YOUR_KEY_HERE"

Only the key first characters and last four are ever displayed again — the full key is shown once at creation and only a one-way hash is stored.

Scopes and the acting person

A key carries scopes in resource:action form — careers:read, careers:write, and so on. :write never implies :read. Independently, every key is bound to an acting person: the API’s effective permission is always the intersection of the key scopes and what that person may do in the app. A 403 tells you which of the two blocked the call by its type: insufficient-scope means grant the key a scope; insufficient-permissions means the acting person cannot do this in the app, and no scope will help. Scope changes take effect on the very next request — nothing is cached.

How people are identified: the person identifier on this API is the email address — in bodies, query filters, and /people/{id}-style path slots (which also accept the opaque id from any response). Every lookup is bounded by the key’s company, and an email held by another company answers exactly like one that does not exist, so the API never confirms an address elsewhere. In a path slot such as /people/{id} that is a 404; in a body or query field it is a 400 with code unknown_person on the named field. Duplicate case-variants of one address in your own data answer 409 instead of a silent pick — see Getting Started.

Scope reference

Every endpoint’s reference page states the scope it needs on its Requires scope line. /ping is the one scope-free endpoint — any valid key can call it. Remember the intersection rule above: a scope grants nothing the acting person cannot already do in the app — it only ever narrows.

Scope	Grants
`skills:read`	Read skills, their versions and activity, and skill requests
`skills:write`	Create and update skills; create and decide skill requests
`people:read`	Read people, their org schema memberships and the reporting structure
`people:write`	Create and update people (bulk provisioning included), manage their org schema memberships, manager, email, access level and lifecycle
`careers:read`	Read careers, career types, levels, assignments, distributions, activity and the grading scale
`careers:write`	Author careers and their structure; assign and unassign people; add, update and remove grading scale rungs
`training:read`	Read training records and approval activity
`training:write`	Create and update training records; record approval decisions
`flags:read`	Read people flags and skill flags, and who holds them
`flags:write`	Create flags; apply and remove them
`org:read`	Read the org structure dimensions
`org:write`	Create and update org structure entries
`learning:read`	Read learning plans, the training library (learning items, reference lists) and learning suggestions
`learning:write`	Assign learnings and update learning plan entries; maintain the training library and decide suggestions
`certifications:read`	Read the certification library and types, a person’s certifications, their history and attachments, and coverage reporting
`certifications:write`	Maintain the certification library and types; record, submit, approve, deny, renew and unassign a person’s certifications
`assessments:read`	Read assessment cycles, participation, assessment grades and reports
`assessments:write`	Administer assessment cycles: create, schedule, scope, exclude, nudge, start and end
`proficiency:read`	Read person skill grades, benchmarks, focus and origin across a population; grade reporting
`proficiency:write`	Grade people on skills, set per-person benchmarks, mark skills not applicable or focused
`surveys:read`	Read survey runs, participation, responses and the frozen question set behind them
`surveys:write`	Administer survey runs and their population; submit responses
`labels:read`	Read labels, the label tree, and which labels an object carries
`labels:write`	Create, update, reorder, reparent and delete labels; attach and detach them

Rotation

Rotating a key issues a replacement (same scopes, same acting person, new secret) while the old key keeps working for an overlap window (24 hours by default). Deploy the new key at your leisure inside the window; the old key stops working when it ends.

Revocation

Revoking a key stops it immediately — the key status is checked live on every request.

What a 401 means

Any authentication failure returns the same generic invalid-credential problem — the API never reveals whether a key exists, expired, was revoked, or was never valid.

Using the API

System Objects

Team Data

Errors

The key

Scopes and the acting person

Scope reference

Rotation

Revocation

What a 401 means

​The key

​Scopes and the acting person

​Scope reference

​Rotation

​Revocation

​What a 401 means

The key

Scopes and the acting person

Scope reference

Rotation

Revocation

What a 401 means