Authentication API

Developer Portal — Getnet

1. Overview

The Authentication service is the entry point for all integrations with the Getnet platform. It is responsible for confirming the identity of the requester and, in return, issuing a temporary access token.

Think of it as the "digital badge" for your integration: without it, no other service on the platform will accept your requests. With it in hand — and while it is still valid — you can freely access the other available resources.

2. Context and Use Cases

Use this service always before calling any other Getnet API. The token generated here is the fundamental requirement for all other operations.

Typical scenarios

Situation	What happens
Your application has just started	Call the authentication API to obtain the first token before any other operation.
The current token is about to expire	Renew the token before it expires to avoid interruptions in the end-user flow.
A request returned `401 Unauthorized`	The token has expired or was malformed — obtain a new one and repeat the operation.
Integration with a new product scope	Request a token with the `scope` corresponding to the set of APIs you wish to use.

3. Main Flow

The flow is straightforward: your application presents its credentials and receives a token that should be reused in all subsequent calls until the informed expiration time.

text

[Your Application] ──600;">POST /token──────────────────────► [Authentication API]
                  (credentials in headers + body)
                ◄──200 OK { access_token, expires_in }──

[Your Application] ──Request + Authorization header──► [Other Getnet APIs]
                ◄──Operation response────────────────

  ↺  Repeat 600;">POST /token when expires_in is close to ending.

text

[Your Application] ──600;">POST /token──────────────────────► [Authentication API]
                  (credentials in headers + body)
                ◄──200 OK { access_token, expires_in }──

[Your Application] ──Request + Authorization header──► [Other Getnet APIs]
                ◄──Operation response────────────────

  ↺  Repeat 600;">POST /token when expires_in is close to ending.

Detailed steps

Prepare your credentials — Have the client_id, client_secret, channel, and scope provided by Getnet during onboarding.
Identify the requester — Build the request body with the data of the user or system initiating the session (branch, login, name, enrollment_number).
Send the request — Make a POST /token with the credentials in the headers and the data in the body.
Store the token — Securely store the returned access_token in your application's memory.
Use the token — Include the access_token in the Authorization header of all calls to other APIs.
Monitor validity — Track the expires_in field (in seconds) and renew the token before it expires.

4. Prerequisites

Before using this service, you will need:

Access credentials — client_id and client_secret issued by Getnet during onboarding. Keep them secure; never expose them on the client side (browser, mobile app).
Access channel (channel) — Identifier of the channel through which your application communicates with Getnet (e.g., partner channel, direct channel). Defined by Getnet during onboarding.
Scope (scope) — Defines which groups of APIs you are authorized to consume. Each scope is granted according to the current commercial contract.
Network access — Connection to the endpoints:
- Sandbox: https://api-homologacao.getnet.com.br:443
- Production: https://api-backoffice.getnet.com.br:443

⚠️ Attention: Never use production credentials in the sandbox environment and vice versa.

5. Quick Integration Guide

Scenario: Obtain the first access token (happy path)

Endpoint: POST /v1/token

What to send

Required headers:

Header	Example	Description
`client_id`	`your-client-id`	Identifier of your application in Getnet.
`client_secret`	`your-client-secret`	Password/secret key of your application.
`channel`	`partner-xyz`	Access channel defined during onboarding.
`scope`	`oob`	Scope for the desired APIs.
`Content-Type`	`application/json`	Format of the request body.

Request body (JSON):

json

{
  "branch": "0001",
  "login": "usuario.exemplo",
  "name": "Usuário Exemplo",
  "enrollment_number": "123456"
}

json

{
  "branch": "0001",
  "login": "usuario.exemplo",
  "name": "Usuário Exemplo",
  "enrollment_number": "123456"
}

What to expect in return

Status 200 OK:

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": "3600"
}

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": "3600"
}

How to use the returned token:

From this moment, include the access_token in all your requests to other APIs:

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

text

Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

💡 The token is valid for 3600 seconds (1 hour). Program your application to renew it before this period.

6. Business Rules

Required fields

Headers — all required:

client_id
client_secret
channel
scope

Body — all required (can be sent as empty string):

branch — Agency or branch of the requester. Used for auditing and channel action traceability.
login — User identifier in the organization. Used for auditing and channel action traceability.
name — Readable name of the user. Used for auditing and channel action traceability.
enrollment_number — User's enrollment number. Used for auditing and channel action traceability.

💡 These fields exist so the channel can identify who performed each action on the platform. If the channel does not need internal traceability, all fields can be sent as an empty string (""). What is not allowed is to omit them or send them as null.

Token validity

The expires_in field is returned as a numeric string representing seconds.
You must not reuse an expired token. Attempting to do so will result in 401 Unauthorized.
There is no "refresh token" endpoint — a new token must be generated with a new call to POST /token.

Scope and permissions

The scope (scope) determines which APIs you can consume with that token.
Calling an API outside the granted scope will result in 403 Forbidden.
If you need to expand the scope, contact Getnet for contract review.

7. Error Handling

Error table

HTTP Code	Name	What it means	What to do
`400`	Bad Request	The request is malformed: a required header is missing, empty, or has an invalid value; or a body field is not allowed.	Check the headers and body. See the `details` field in the response to identify exactly which field has a problem.
`401`	Unauthorized	The provided credentials (`client_id` and `client_secret`) are invalid or missing.	Confirm you are using the correct credentials for the environment (sandbox or production). Never mix credentials between environments.
`403`	Forbidden	Valid authentication, but your application does not have permission to access the requested resource with the current scope.	Check the `scope` sent. If access is legitimate, request scope release from the Getnet team.
`500`	Internal Server Error	Unexpected error on the Getnet platform side.	Try again after a few moments. If the problem persists, contact Getnet support with the timestamp and request headers to facilitate diagnosis.

Error response examples

400 — Missing or invalid header:

json

{
  "status_code": 400,
  "name": "HeaderValidation",
  "message": "Bad Request",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "channel is invalid",
      "description_detail": "\"channel\" is not allowed to be empty"
    }
  ]
}

json

{
  "status_code": 400,
  "name": "HeaderValidation",
  "message": "Bad Request",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-400",
      "description": "channel is invalid",
      "description_detail": "\"channel\" is not allowed to be empty"
    }
  ]
}

401 — Invalid credentials:

json

{
  "status_code": 401,
  "name": "Unauthorized",
  "message": "Unauthorized",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-401",
      "description": "Unauthorized",
      "description_detail": "CODE 01"
    }
  ]
}

json

{
  "status_code": 401,
  "name": "Unauthorized",
  "message": "Unauthorized",
  "details": [
    {
      "status": "DENIED",
      "error_code": "GENERIC-401",
      "description": "Unauthorized",
      "description_detail": "CODE 01"
    }
  ]
}

💡 Tip: Always inspect the details array in error responses. It contains the exact field and reason for the failure, greatly speeding up diagnosis.

8. Glossary

Term	Definition
access_token	Temporary credential issued by the authentication API after successful validation. Must be sent in all requests to the platform's APIs.
expires_in	Lifetime of the `access_token`, in seconds, counted from the moment of issuance. After this period, the token is invalid and a new one must be requested.
client_id	Unique identifier of the application (client) registered in Getnet. Similar to a "username" for systems.
client_secret	Secret key associated with the `client_id`. Should be treated with the same care as a password — never exposed in logs or source code.
channel	Communication channel through which the application accesses the Getnet platform (e.g., partner, integrator, direct channel). Defined during onboarding.
scope	Set of permissions that determines which APIs and resources the application can access with the generated token.
branch	Code of the agency or branch associated with the token requester. Used for traceability and auditing purposes.
enrollment_number	User's enrollment number within the organization. Uniquely identifies the operator or system that started the session.
login	Textual identifier of the user in the organization (username/corporate login).
error_code	Internal Getnet code that categorizes the type of error occurred (e.g., `GENERIC-400`, `GENERIC-401`). Useful when contacting technical support.
Homologação	Test environment, separate from production, where integrations are validated without real impact. URL: `api-homologacao.getnet.com.br`.
Produção	Real environment, with actual transactions and data. URL: `api-backoffice.getnet.com.br`.

On this page

Authentication API