Client Credentials Flow
Authorization on behalf of the application itself.
Suitable for server-side applications that perform actions on behalf of themselves, for example, chatbots.
In the Client Credentials Flow, the application receives an access token from Space by sending it a
client_id
and aclient_secret
.If you use Space SDK in your application, you can implement the flow with the help of the
SpaceHttpClient().withServiceAccountTokenSource()
method.Not all operations may be accessible using the Client Credentials Flow. Many actions (for example, posting an article draft) require user consent and cannot be performed with application credentials. For actions that should be performed on behalf of the user, use other authorization flows, for example Resource Owner Password Credentials Flow.
For more details on the flow, refer to Client credentials flow specification.
The application requests an access token from Space by sending its client_id
and client_secret
. The SpaceHttpClient
class provides the withServiceAccountTokenSource
method for working with the Client Credentials flow. For example:
// URL of your Space instance
const val spaceUrl = "https://mycompany.jetbrains.space"
// 'clientId' and 'clientSecret' are issued when you
// register the application in Space
// or when the application is installed to Space by a user
val clientId = System.getenv("JB_SPACE_CLIENT_ID")
val clientSecret = System.getenv("JB_SPACE_CLIENT_SECRET")
// Create a base Space client
val baseClient = SpaceHttpClient(HttpClient())
// Make a request.
// The "**" arg defines the scope
val spaceClient = baseClient.withServiceAccountTokenSource(
clientId, clientSecret, spaceUrl, "**")
val absences = spaceClient.absences.getAllAbsences()
To obtain an access token from Space, the application should make a request to the token endpoint <Space service URL>/oauth/token
. Use the Authorization
header with Basic
content to provide client_id
and client_secret
.
Put the following parameters to the entity-body of the HTTP request in the application/x-www-form-urlencoded
format with UTF-8 character encoding. See the example below.
- grant_type
Required. Specifies the grant type in an OAuth 2.0 request. Set value to
client_credentials
.
The Authorization
header must have the following format:
Authorization: Basic <base64(client_id + ":" + client_secret)>
Combine the client_id
and client_secret
in a single string using semicolon as a delimiter and encode it into Base64 format.
For example:
POST /oauth/token
Host: mycompany.jetbrains.space
Authorization: Basic dmFsaWQtc2VydmljZS1pZDp2YWxpZC1zZXJ2aWNlLXNlY3JldA==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=**
If the request is valid, Space will authenticate the application.
If the access token request is valid and authorized, Space will issue an access token and optional refresh token. It will construct the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:
Parameter | Description |
---|---|
access_token | The access token issued by Space. |
token_type | The type of the token issued by Space. Value is case insensitive. |
expires_in | The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. |
scope | Optional, if identical to the scope requested by the application; otherwise, required. A space separated list of rights required to access specific resources in Space. |
The parameters are included in the entity-body
of the HTTP response using the "application/json" media type. The parameters are serialized into JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.
Space includes the HTTP "Cache-Control" response header field with a value of "no-store" in any response containing tokens, credentials, or other sensitive information, as well as the "Pragma" response header field with a value of "no-cache".
Example:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"token_type": "Bearer",
"expires_in": 600,
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzNThlMDRlOS1jNDc1LTRkNGUtOGM4OS1lODA3ZTQxNjk3MmMiLCJhdWQiOiIzNThlMDRlOS1jNDc1LTRkNGUtOGM4OS1lODA3ZTQxNjk3MmMiLCJvcmdEb21haW4iOiJqZXRicmFpbnMudGVhbSIsInNjb3BlIjoiKioiLCJuYW1lIjoiTXkgU2VydmljZSIsImlzcyI6Imh0dHBzOi8vamV0YnJhaW5zLnRlYW0iLCJwcmluY2lwYWxfdHlwZSI6IlNFUlZJQ0UiLCJleHAiOjE1NjQ1MDU0MzAsImlhdCI6MTU2NDUwNDgzMH0._1uLmGWUfeG52p4_LcLdZN29at14CGG_RE4KusWY34A",
"refresh_token": null,
"scope": "**"
}
If the request failed application authentication or is invalid, Space responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response:
- error
A single ASCII [USASCII] error code from the following:
invalid_request
— The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the application, or is otherwise malformed.invalid_client
— Application authentication failed (e.g., unknown application, no application authentication included, or unsupported authentication method). Space may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the application attempted to authenticate via the "Authorization" request header field, the Space server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the application.invalid_grant
— The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another application.unauthorized_client
— The authenticated application is not authorized to use this authorization grant type.unsupported_grant_type
— The authorization grant type is not supported by Space.invalid_scope
— The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
Thanks for your feedback!