Client Credentials Flow

Client credentials grant authentication flow (client credentials flow)

The client credentials grant (client credentials flow) is used when applications request an access token to access their own resources, not on behalf of a user.

At Kobana this flow is used when authentication needs to be done through an OAuth application registered and approved in the system.

Libraries

There are OAuth2 libraries for almost all languages since it is a widely used protocol in the software industry and by companies like Google and Facebook.

Choose a library before you start.

Application Registration

To get started you need to register your application. We will provide you with a client_id and client_secret.

In this case it is not necessary to provide us with a Redirect URL redirect_uri.

Endpoints

Environment	URL
Sandbox	POST https://app-sandbox.kobana.com.br/oauth/token
Production	POST https://app.kobana.com.br/oauth/token

How it works

The client credentials flow requests a token from the credentials of a registered and approved application. To request the token:

• Use the client_id and client_secret you obtained from us during registration to make the request to request a token. Optionally include the scope to access specific permissions.
• Generate an access_token by making a request to the Token URL using the client_credentials grant type.
• Use the access_token received to make API requests.

Only some endpoints accept authentication this way.

Step-by-step guide

1. Assuming the following information:

* **Client ID** -> xxxxxxxxxx
* **Client Secret** -> yyyyyyyyyy

2. Make a POST request to the address below to receive the access token.

https://app-sandbox.kobana.com.br/oauth/token?grant_type=client_credentials&scope=write&client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy

Shell

curl -i \
-d 'grant_type=client_credentials&scope=write&client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://app-sandbox.kobana.com.br/oauth/token'

Ruby

require 'boletosimples'

BoletoSimples.configure do |c|
  c.environment = :sandbox
  c.application_id = 'fc4e525ff3'
  c.application_secret = '95ea9a477d'
end

puts BoletoSimples.configuration.client_credentials

Error response:

HTTP/1.1 401 Unauthorized
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 401 Unauthorized
Content-Type: application/json; charset=utf-8
...

{"error":"invalid_client","error_description":"Autenticação do cliente falhou devido a um cliente desconhecido, a falta de inclusão da autenticação do cliente, ou a um método não suportado de autenticação."}

Success response:

HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{"access_token":"ada046e3cc","token_type":"bearer","scope":"write","created_at":1434463054}

You can save this access token indefinitely. The token does not expire.

3. Now you can use the access_token to make API calls.

Note that only some endpoints allow authentication using this flow.