Postman

Use the Postman collection to test Asaas API endpoints in Sandbox before implementing calls in your application.

When to use the Postman collection

Use the collection when you need to:

• Validate authentication, headers, and URLs before writing code.
• Explore documented endpoints without building requests manually.
• Reproduce integration errors and compare API behavior between Sandbox and Production.
• Share a set of requests with your team during development.

Prerequisites

Before running requests:

1. Install Postman or sign in via browser.
2. Create a test account in the Asaas Sandbox.
3. Generate an API key for the environment you want to use. See the API Keys guide.
4. Read the Authentication guide to confirm the required headers.

⚠️

Do not share your API key in public workspaces, screenshots, repositories, or conversations. The key identifies your account and authorizes calls on your behalf.

Access and fork the collection

1. Open the Asaas API in Postman:

Open Asaas API on Postman

2. In the left sidebar, expand Asaas API and click Collection Asaas.

3. Click Fork in the top-right corner and select the Workspace where you want to copy the collection.

Configure authentication and environment

After forking, configure the collection or the request you want to test with the headers below.

Use the correct URL for the environment you want to test:

⚠️

Sandbox and Production API keys are different. If you use a Production key with a Sandbox URL, or vice versa, the API will return an authentication error.

If the collection uses Postman environment variables, update the base URL variable and the API key variable before sending the first request. If not using variables, check these values directly in the request headers and URL.

Testing a request

1. Select an endpoint inside Collection Asaas.
2. Confirm the URL points to the desired environment.
3. Confirm the Content-Type, User-Agent, and access_token headers are present.
4. Click Send.
5. Check the HTTP status and response body.

A successful response varies by endpoint, but should return a 2xx status. If authentication fails, the API returns 401 Unauthorized with details in the response body.

Example error when the key is used in the wrong environment:

{
  "errors": [
    {
      "code": "invalid_environment",
      "description": "The provided API key does not belong to this environment"
    }
  ]
}

Example error when the authentication header is missing:

{
  "errors": [
    {
      "code": "access_token_not_found",
      "description": "The authentication header 'access_token' is required and was not found in the request"
    }
  ]
}

Troubleshooting

Related content

• Authentication: see required headers, environment URLs, and authentication errors.
• API Keys: learn how to create and manage your API key.
• Sandbox: test your integration with fictional data before going to Production.