v9 (current) v8
Edit Page

OAuth 2.0 Client Credentials Grant

RESTHeart

🔧 Configuration

▼
Sets localhost:8080 with admin:secret
Values are saved in your browser

⚡ Setup Guide

▼

To run the examples on this page, you need a RESTHeart instance.

Option 1: Use RESTHeart Cloud (Recommended)

The fastest way to get started is with RESTHeart Cloud. Create a free service in minutes:

  1. Sign up at cloud.restheart.com

  2. Create a free API service

  3. Set up your root user following the Root User Setup guide

  4. Use the configuration panel above to set your service URL and credentials

Tip
 All code examples on this page will automatically use your configured RESTHeart Cloud credentials.

Option 2: Run RESTHeart Locally

If you prefer local development, follow the Setup Guide to install RESTHeart on your machine.

Note
 Local instances run at http://localhost:8080 with default credentials admin:secret
Note
 Available from RESTHeart v9.4.

The client_credentials grant type enables machine-to-machine authentication: a service, script, or CI/CD pipeline exchanges its own credentials for a JWT access token without any user interaction.

Overview

RESTHeart’s built-in OAuth 2.1 authorization server supports the client_credentials grant type (RFC 6749 §4.4) alongside the password and authorization_code grants.

Typical use cases:

  • Backend services calling the RESTHeart API

  • Automated scripts and batch jobs

  • CI/CD pipelines accessing protected endpoints

Discovery Endpoint

Clients can auto-configure by fetching the Authorization Server Metadata document (RFC 8414):

http GET [RESTHEART-URL]/.well-known/oauth-authorization-server
{
  "issuer": "https://api.example.com",
  "token_endpoint": "https://api.example.com/token",
  "grant_types_supported": ["authorization_code", "password", "client_credentials"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"]
}
Note
 The discovery endpoint must be explicitly enabled. See OAuth 2.0 / 2.1 for configuration details.

Token Request

Send a POST to /token with grant_type=client_credentials as application/x-www-form-urlencoded:

HTTPie

http -f POST [RESTHEART-URL]/token \
  grant_type=client_credentials \
  client_id=myapp \
  client_secret=secret

cURL

curl -i -X POST [RESTHEART-URL]/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=myapp&client_secret=secret"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

Use the returned token as a Bearer credential on subsequent requests:

http GET [RESTHEART-URL]/mycollection \
  "Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

How It Works

The FormDataToBasicAuthInterceptor intercepts the form POST and transparently converts the client_id / client_secret fields into an HTTP Basic Authorization header before the authentication pipeline runs. This means the same authenticator (e.g., mongoRealmAuthenticator) handles both browser password flows and machine client credentials flows without any additional configuration.

POST /token (form body)
  → FormDataToBasicAuthInterceptor
      → converts client_id + client_secret → Authorization: Basic ...
  → auth pipeline (authenticator + token manager)
  → JWT response

  • OAuth 2.0 / 2.1 — Full reference for all grant types, the Authorization Code + PKCE flow, and configuration

  • Permission Management — Controlling what authenticated clients can access