API keys and identity reference

What does the identity group cover?

Five operations. Four manage the API keys of an organization, and one tells a caller who it is. Keys for a named agent are minted in the agents group. Sign-in for people is in the auth group.

How is an API key created?

POST /v1/api-keys takes a label and, when you want them, an environment, a number of days until expiry and a list of scopes. Without scopes the key is given the default set. The schema says '*' asks for all of them. The answer is the only one that carries the secret. Store it then. Later reads return the prefix, the scopes, the environment and the dates.

The body also has connected_app. It marks a key that an app such as a command line extension uses for a person. The organization's auto-send setting then binds it. The policies group has the setting.

Each API key belongs to one environment. Test keys reach the sandbox and the test wallet. Live keys reach the carrier and real money. The header X-FFA-Environment does not change the environment of a key.

How do I rotate an API key without downtime?

POST /v1/api-keys/{key_id}/rotate answers 201 with a new key and its secret. The OpenAPI document states the two rules of a rotation. The replacement keeps the original expires_at, including no expiry. The old secret works for up to 24 hours, capped by its existing expiry.

So a rotation is three steps. Rotate, deploy the new secret, and let the old one lapse. The new key names the one it replaced in rotated_from_id, which keeps the history readable in the list.

How do I revoke a key?

DELETE /v1/api-keys/{key_id} revokes it at once. There is no overlap. A call with the revoked secret answers 401.

What does the list of keys return?

GET /v1/api-keys returns metadata only. Each row has the id, the label, the prefix, the scopes, the environment and the agent, if there is one. It also says when the key was created, last used, rotated and revoked. The summary of the operation says so in words, "metadata only". No route returns a secret after the call that created it.

How does a caller find out who it is?

GET /v1/me answers with the actor, the organization, the project, the environment, the key id and prefix, and the scopes the credential carries. It needs a valid credential and no scope. Call it first when an API key behaves in a way you did not expect. It shows whether the key is a test or a live one and which scopes it holds.

Which scope guards API keys?

All four operations on keys need key:admin. An agent key is never issued that scope, so an agent cannot create, rotate or revoke a key, its own included. A person signed in to the dashboard, or a key of the organization that holds the scope, runs them.

curl https://api.faxforagents.com/v1/api-keys \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"label":"example"}'

curl https://api.faxforagents.com/v1/api-keys/KEY_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/api-keys/KEY_ID/rotate \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/me \
  -H "Authorization: Bearer ffa_test_..."