Permissions

Every credential carries a set of scopes: the actions it may perform. heru assigns them from your contract, and the token lists them in scope. A call that needs a scope your credential lacks answers 403 INSUFFICIENT_SCOPE.

Scopes are per action, so a credential can be as narrow as a system needs: a terminal can create charges without being able to void them. Ask your account team for the scopes each of your systems needs.

Token response

{
  "access_token": "eyJhbGciOiJFUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:write invoices:read invoices:download"
}

Batches also need the scope of their type: a batch of invoices needs batches:write and invoices:write. A token with a scope outside your contract is refused at /oauth/token with invalid_scope.

Fiscal validation

Scope	Allows	Operations
`fiscal_validations:read`	Read fiscal validations.	`GET /fiscal-validations` `GET /fiscal-validations/{id}`
`fiscal_validations:write`	Start fiscal validations with the SAT.	`POST /fiscal-validations`

Scope	Allows	Operations
`social_security_validations:read`	Read NSS lookups and IMSS registrations.	`GET /social-security-validations` `GET /social-security-validations/{id}`
`social_security_validations:write`	Look up NSS and start IMSS registrations.	`POST /social-security-validations`

Workers, e.firma and CSD

Scope	Allows	Operations
`workers:read`	Read workers and the workers feed.	`GET /workers/{id}` `GET /workers/report`
`workers:write`	Register and remove workers, and create their enrollment links.	`POST /workers` `DELETE /workers/{id}` `POST /workers/{id}/enrollment`
`workers:csd`	Request a worker's CSD from the SAT with their e.firma.	`POST /workers/{id}/csd`
`signatures:read`	Read signature requests.	`GET /signatures/{id}`
`signatures:write`	Send documents for a worker to sign.	`POST /signatures`

Invoices

Scope	Allows	Operations
`invoices:read`	Read invoices.	`GET /invoices` `GET /invoices/{id}`
`invoices:write`	Issue invoices.	`POST /invoices`
`invoices:cancel`	Cancel invoices with the SAT.	`DELETE /invoices/{id}`
`invoices:download`	Get download links for the XML and PDF of invoices.	`GET /invoices/{id}/download`

Retention certificates

Scope	Allows	Operations
`retention_certificates:read`	Read retention certificates.	`GET /retention-certificates/{id}`
`retention_certificates:write`	Issue retention certificates.	`POST /retention-certificates`
`retention_certificates:cancel`	Cancel retention certificates with the SAT.	`DELETE /retention-certificates/{id}`
`retention_certificates:download`	Get download links for the XML and PDF of retention certificates.	`GET /retention-certificates/{id}/download`

Batches

Scope	Allows	Operations
`batches:read`	Read batches and their reports.	`GET /batches/{id}`
`batches:write`	Create, process, pause, resume and cancel batches from a CSV. Each batch also needs the scope of its type, e.g. invoices:write.	`POST /batches` `POST /batches/{id}/process` `POST /batches/{id}/pause` `POST /batches/{id}/resume` `POST /batches/{id}/cancel`

Point of sale

Scope	Allows	Operations
`merchants:read`	Read merchants.	`GET /merchants` `GET /merchants/{id}`
`merchants:write`	Add merchants and create onboarding links.	`POST /merchants` `POST /merchants/{id}/onboarding`
`merchants:csd`	Upload or replace a merchant's CSD.	`PUT /merchants/{id}/csd`
`merchants:console`	Create links to a merchant's console.	`POST /merchants/{id}/console-link`
`charges:read`	Read charges.	`GET /charges` `GET /charges/{id}`
`charges:write`	Create charges.	`POST /charges`
`charges:void`	Void charges.	`POST /charges/{id}/void`

Branding

Scope	Allows	Operations
`branding:read`	Read the brand of your merchants.	`GET /branding/merchants/{id}`
`branding:write`	Set the brand and logo of your merchants.	`PUT /branding/merchants/{id}` `PUT /branding/merchants/{id}/logo` `DELETE /branding/merchants/{id}/logo`

Reports

Scope	Allows	Operations
`reports:read`	Read the retentions and usage reports.	`GET /reports/retentions` `GET /reports/usage`

Webhooks

Scope	Allows	Operations
`webhooks:read`	Read webhook subscriptions and their deliveries.	`GET /webhooks` `GET /webhooks/{id}` `GET /webhooks/{id}/deliveries`
`webhooks:write`	Create and manage webhook subscriptions, rotate secrets, test and replay deliveries.	`POST /webhooks` `PATCH /webhooks/{id}` `DELETE /webhooks/{id}` `POST /webhooks/{id}/secret` `POST /webhooks/{id}/test` `POST /deliveries/{id}/replay`

Fiscal validationCopy Anchor Link

Social security (IMSS)Copy Anchor Link

Workers, e.firma and CSDCopy Anchor Link

InvoicesCopy Anchor Link

Retention certificatesCopy Anchor Link

BatchesCopy Anchor Link

Point of saleCopy Anchor Link

BrandingCopy Anchor Link

ReportsCopy Anchor Link

WebhooksCopy Anchor Link

On this page