- Concepts
- API Keys
Concepts
API Keys
Scopes, environment, and expiration of organization keys.
Each organization can have several API Keys, for example one for the sandbox and another for production.
How to generate one
There are two ways:
- Together with the organization: in Create organization, send
generateApiKey: trueandapiKeyOptions. The key comes back inapiKey. - Later: use
POST /enterprise/organizations/{organizationId}/api-keys. The key comes back at the root of the response.
In both cases the response includes:
| Field | Description |
|---|---|
keyId | The key ID. |
rawKey | The value for the x-api-key header. |
The rawKey is shown only once. If it is lost, generate a new key.
Key options
{
"name": "integracao-nfe-homolog",
"scopes": "nfe:emit,nfe:read",
"tpAmb": "HOMOLOGACAO",
"expirationPreset": "1y"
}
| Field | Description |
|---|---|
name | A name to identify the key. |
scopes | Permissions, comma-separated. See below. |
tpAmb | HOMOLOGACAO (sandbox) or PRODUCAO (production). The key only issues in the chosen environment. |
expirationPreset | Validity from creation. E.g. 1y (one year). |
Scopes
| Scope | Allows |
|---|---|
nfe:emit | Issuing NF-e and registering events |
nfe:read | Querying NF-e and events |
nfse:emit | Issuing NFS-e |
nfse:read | Querying NFS-e |
Give each key only the scopes the integration needs.
Environment
The invoice’s environment comes from the API Key: a HOMOLOGACAO key issues in the sandbox and a PRODUCAO key in production. Do not send the environment in the payload.
Integrate and test with a HOMOLOGACAO key. Generate the PRODUCAO key only when you go live.