---
title: "Client Credentials Flow"
description: "OAuth has a flow called client credentials, that comes in handy when there are requests to your APIs that are not involving a user. Using the Client Credentials flow, it's possible to let servers communicate with your API without modifying the APIs themselves."
url: "https://curity.io/resources/learn/client-credentials/"
date: "2018-10-17"
area: "tutorials"
topic: "howtos"
pagegroup: "flows"
---

# Client Credentials Flow

OAuth 2.0 has a flow called [client credentials](https://www.rfc-editor.org/rfc/rfc6749#section-4.4), that comes in handy when there are requests to your APIs that are not involving a user. With the Client Credentials flow it is possible to let servers communicate with an API without modifying the APIs themselves.

## Overview

### Token Endpoint

![Illustration with the steps in the client credentials flow](https://curity.io/images/resources/standards/oauth/flows/cc-flow-01.svg?v=20210408) 

1.  The Client makes a POST request to the OAuth Server
2.  The OAuth Server issues the Access Token immediately and responds to the client

To learn more about the client parameters of the Client Credentials flow see [OAuth Client Credentials Flow](https://curity.io/resources/learn/oauth-client-credentials-flow/).

### Pre-requisites

This tutorial builds on the configuration setup described in the steps [First Configuration](https://curity.io/resources/learn/first-config/) and [Configure an Authenticator](https://curity.io/resources/learn/username-password-authenticator/) under the menu [Getting Started](https://curity.io/resources/getting-started/). If you have not gone through those steps yet, you can visit the guides by clicking on the links.

You may run this tutorial on a custom setup also, but keep in mind that names and URLs may be different, as well as the capabilities configured in the profiles.

## Setup in the Curity Identity Server

Visit the **Profiles** screen and click the **Token Service**. On the right select **Clients** and click **New**.

### New Client

Give the client an ID (eg. `server` for system client).

![New Client](https://curity.io/images/resources/operate/tutorials/standards/cc-flow/config-create-client.jpg)

### Capabilities

In the **Summary** table locate the **Capabilities** row and click on the **Edit** button.

Select the **Client Credentials Flow** capability and click **Next**.

![Capabiltiy](https://curity.io/images/resources/operate/tutorials/standards/cc-flow/config-capability.jpg)

### Client Authentication

For client authentication select `secret` and enter or generate a secret value. Make sure to remember the value since it cannot be retrieved later, though you can reset it if required.

![Secret](https://curity.io/images/resources/operate/tutorials/standards/generic/config-client-authentication.jpg?v=20261026)

### Add a Scope

Next, locate the **Scopes and Claims** section and select a scope, e.g. `read`, from the list of scopes in the dropdown menu, to add that scope to the client. Alternatively, use the **\+ New** button to add a new scope and automatically add it to the client.

![Add Scope](https://curity.io/images/resources/operate/tutorials/standards/generic/add-read-scope.jpg?v=20261030)

### Commit

Make sure to remember to commit the changes in the **Changes -> Commit** menu.

## Using the Client

To implement or use the client the following steps are needed.

1.  Provide the new client with the client\_id (`server`) and the secret
2.  Before it can call the API, get a new access token
3.  Put the access token in the `Authorization` header and call the API

### Retrieve an Access Token

We recommend to use [OAuth Tools](https://oauth.tools/?utm_source=curity.io&utm_medium=Link&utm_content={props.utmContent}) for testing. It is a powerful and convenient tool to explore OAuth and OpenID Connect. Checkout the tutorial [Exposing the Curity Idenitiy Server With ngrok](https://curity.io/resources/learn/expose-local-curity-ngrok/) for guidance on how to work with OAuth Tools and a local installation of the Curity Identity Server.

You can also just run the following command to craft the request:

```shell
curl -k -X POST \
  https://localhost:8443/oauth/v2/oauth-token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=server&client_secret=Secr3t!'
```

Curl against localhost

When using curl against localhost and HTTPS you will need to use -k to disable certificate verification.

#### Request a Scope

If you added a scope to the client configuration, you can append that to the form parameters.

```shell
curl -k -X POST \
  https://localhost:8443/oauth/v2/oauth-token \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=server&client_secret=Secr3t!&scope=read'
```

The request is always of content type `application/x-www-form-urlencoded`. The following parameters should be sent:

-   `client_id=server`
-   `client_secret=Secr3t!`
-   `grant_type=client_credentials` (constant)
-   `scope=read` (optional, a space separated list of the scopes configured on the client)

This returns a json response with the access token:

```javascript
{
    "access_token": "0470b16b-7bf8-4fa3-9ae1-6a10e0f0b699",
    "scope": "read", //only if scope=read was requested
    "token_type": "bearer",
    "expires_in": 299
}
```

### Call an API With the Access Token

The token lives for 299 seconds according to the response from the server. This is configurable on the client settings and in the profile. When the token expires the API should respond with a `401` telling the client to get a new token.

To call the API, the token should be added to the request in the `Authorization` header on the form:

```text
Authorization: Bearer 0470b16b-7bf8-4fa3-9ae1-6a10e0f0b699
```

Specify the keyword `Bearer`, then leave a single space and append the token.

The call looks as follows:

```shell
curl -X GET \
  https://example.com/hello_world \
  -H 'Authorization: Bearer 0470b16b-7bf8-4fa3-9ae1-6a10e0f0b699'
```

## Conclusion

The Client Credentials call is useful when there is no user involved in the call. It is also very handy during development since it provides a simple way for a client to retrieve an access token to use when calling APIs.
