getnet-oauth2-token

OAuth2 Token API — Authentication via Client Credentials Flow for the Getnet environment, issuing short-lived access tokens for applications consuming Getnet APIs.

Overview

getnet-oauth2-token is the authentication API that issues access tokens for applications consuming Getnet APIs. It implements the OAuth2 Client Credentials flow: an application exchanges its credentials (client_id and client_secret) for a short-lived access_token.

The returned token is mandatory and must be sent on all subsequent Getnet API calls, ensuring that only authorized applications can access protected resources.

Auth standard: OAuth2 — Client Credentials Flow
Version: 1.0.0
Response format: JSON
Contact: Getnet Developer — https://developers.getnet.com.br

Architecture

text

API Consumer (Application)  
       │  
       │  600;">POST /token (client_id + client_secret)  
       ▼  
┌─────────────────────────────────────────┐  
│      Getnet OAuth2 Authorization Server  │  
│                                          │  
│   Validate credentials → issue JWT       │  
│   access_token (Bearer, expires_in)      │  
└─────────────────────────────────────────┘  
       │  
       │  access_token (Bearer, expires_in)  
       ▼  
Getnet Resource APIs  
   Authorization: Bearer <access_token>

text

API Consumer (Application)  
       │  
       │  600;">POST /token (client_id + client_secret)  
       ▼  
┌─────────────────────────────────────────┐  
│      Getnet OAuth2 Authorization Server  │  
│                                          │  
│   Validate credentials → issue JWT       │  
│   access_token (Bearer, expires_in)      │  
└─────────────────────────────────────────┘  
       │  
       │  access_token (Bearer, expires_in)  
       ▼  
Getnet Resource APIs  
   Authorization: Bearer <access_token>

Key Design Decisions

Concern	Solution
Grant type	OAuth2 `client_credentials` (machine-to-machine, no end user)
Token format	JWT `access_token` returned as `Bearer`
Token lifetime	Time-boxed via `expires_in` (seconds); reuse until near expiry
Request encoding	`application/x-www-form-urlencoded`
Error contract	OAuth2 standard fields (`error`, `error_description`)
Scope	Granted permissions returned in `scope` (e.g. `wlb:whitelabel:rw`)

Environments

Environment	Base URL	Description
Homolog	`https://api-homologacao.getnet.com.br/auth/oauth2`	Testing/homologation environment
Development	`https://developers.getnet.com.br`	Development environment

API Endpoints

Get Access Token — `POST /token`

Generates an access token using the OAuth2 Client Credentials flow. The returned token must be used in subsequent calls to the Getnet API.

Attribute	Value
Method	`POST`
Operation	`getAccessToken`
Category	Authentication
Content-Type	`application/x-www-form-urlencoded`

Request parameters (body — form-urlencoded):

Field	Type	Required	Description
`grant_type`	String	Yes	OAuth2 grant type. Must always be `client_credentials`.
`client_id`	String	Yes	Unique client identifier provided by Getnet.
`client_secret`	String (password)	Yes	Client secret key provided by Getnet.

Responses: 200 OK (token generated), 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

Response body (200):

json

{  
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",  
  "token_type": "Bearer",  
  "expires_in": 3600,  
  "scope": "wlb:whitelabel:rw"  
}

json

{  
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",  
  "token_type": "Bearer",  
  "expires_in": 3600,  
  "scope": "wlb:whitelabel:rw"  
}

Schemas

TokenResponse

Field	Type	Required	Description
`access_token`	String	Yes	JWT access token for authenticating subsequent API calls.
`token_type`	String	Yes	Token type. Usually `Bearer`.
`expires_in`	Integer	Yes	Token expiration time, in seconds.
`scope`	String	No	Permission scope granted to the token.

ErrorResponse

Field	Type	Required	Description
`error`	String	Yes	OAuth2 error code.
`error_description`	String	No	Human-readable error description.

Authentication Flow

The Client Credentials flow is used for machine-to-machine (server-to-server) integrations, where no end user is involved. The application itself owns the credentials.

Getnet provisions client_id + client_secret to the application
Application → POST /token (grant_type=client_credentials, client_id, client_secret)
Server validates credentials → returns access_token (+ token_type, expires_in, scope)
Application calls Getnet APIs with header: Authorization: Bearer <access_token>
On token expiry → repeat step 2 to obtain a new token

Error Handling

All error responses follow the OAuth2 standard, exposing error and error_description.

HTTP Status	`error` (example)	`error_description` (example)	Meaning
`400 Bad Request`	`invalid_request`	Invalid client credentials	Missing/incorrect parameters
`401 Unauthorized`	`unauthorized_client`	Invalid client secret	Invalid credentials
`500 Internal Server Error`	—	—	Unexpected server error

Error body example:

json

{  
  "error": "invalid_request",  
  "error_description": "Invalid client credentials"  
}

json

{  
  "error": "invalid_request",  
  "error_description": "Invalid client credentials"  
}

Usage Example

Request the token (cURL):

text

600;">curl -X 600;">POST "https://api-homologacao.getnet.com.br/auth/oauth2/token" \  
  -H "Content-Type: application/x-www-form-urlencoded" \  
  -d "grant_type=client_credentials" \  
  -d "client_id={CLIENT-ID}" \  
  -d "client_secret={CLIENT-SECRET}"

text

600;">curl -X 600;">POST "https://api-homologacao.getnet.com.br/auth/oauth2/token" \  
  -H "Content-Type: application/x-www-form-urlencoded" \  
  -d "grant_type=client_credentials" \  
  -d "client_id={CLIENT-ID}" \  
  -d "client_secret={CLIENT-SECRET}"

Use the token on subsequent calls:

text

600;">GET /some-getnet-api HTTP/1.1  
Host: api-homologacao.getnet.com.br  
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

text

600;">GET /some-getnet-api HTTP/1.1  
Host: api-homologacao.getnet.com.br  
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Best Practices

Reuse the token — valid for expires_in seconds (e.g. 3600s = 1h). Cache it and refresh only near expiry instead of requesting one per call.
Protect credentials — never expose client_id / client_secret in public source code, logs, or front-end code.
Respect scopes — use only the resources permitted by the granted scope.
Handle errors — treat 400/401 (review credentials/parameters) and 500 (controlled retry) distinctly.
Use the right environment — validate against the homolog URL before moving to production.

Getnet OAuth2 authentication — https://developers.getnet.com.br

On this page

getnet-oauth2-token

getnet-oauth2-token

Overview

Architecture

Key Design Decisions

Environments

API Endpoints

Get Access Token — POST /token

Schemas

TokenResponse

ErrorResponse

Authentication Flow

Error Handling

Usage Example

Best Practices

Get Access Token — `POST /token`