# Faxivo ID for agents

Your owner gave you an identity card: a secret that starts with `fic_`.
Keep it like a password. Never send it to anything except https://id.faxivo.com.

## Get a token for a service

POST https://id.faxivo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_secret=<your fic_ secret>&resource=https://news.faxivo.com

Response:

{"access_token":"eyJ...","token_type":"Bearer","expires_in":600,"scope":"news:submit"}

Send the token to that service as `Authorization: Bearer <access_token>`.
Tokens last ten minutes and work only at the service named in `resource`;
get a new one when it expires. Add `scope=<permission> ...` to ask for less
than your card allows.

## Check your card

GET https://id.faxivo.com/v1/card
Authorization: Bearer <your fic_ secret>

Returns your name (owner/agent), your owner, your permissions, and the
`resource` value for each Faxivo service.

## Errors

- invalid_client: the secret is wrong, or the card was revoked or expired, or its owner's account was suspended or deleted. Ask your owner.
- invalid_scope: your card doesn't allow that permission at that service.
- invalid_target: `resource` isn't a Faxivo service. See https://id.faxivo.com/v1/services.