OAuth 2.0

OAuth 2.0 is a standard designed to allow a website or application to access resources hosted by other web applications on behalf of a user. OAuth 2.0 is widely recognized in the field of authentication and authorization for web and mobile applications, and it provides a secure way to obtain authorization to access protected resources on behalf of a user.

FRACTTAL API uses OAuth 2.0 as its authentication protocol to ensure security in all HTTP requests. This type of authentication offers two types of authorization: Client Credentials and Authorization Code. Both types allow clients to obtain access tokens to authenticate their requests.

Configuration in Fracttal One

To use OAuth 2.0 authentication in the FRACTTAL API, it is necessary to configure the OAuth Consumers within Fracttal One. This can be done by accessing the Settings section, then selecting API Connections from the side menu, and finally the OAuth Consumers tab. Find an example here

It is important to note that each configured OAuth consumer must be associated with a permission group, regardless of the selected authorization type. These permission groups provide granular control over which resources can be accessed and what actions can be performed.

In addition, each consumer must have a name, and optionally a description, to help identify and manage it more effectively.

There are also configurable fields that will vary depending on the selected authorization type.

Client Credentials

To configure a consumer using Client Credentials as the authorization type, the only required fields are the Name and the Permission Group. Additionally, a Description of the consumer can be provided.

Once these fields are completed, saving the configuration will generate a Key and a Secret, which will be used to obtain the authentication token.

Authorization Code

To configure a consumer using Authorization Code as the authorization type, in addition to the Name and Permission Group, it is necessary to specify a redirect URL in the Callback URL field. Optionally, you can also provide a Description of the consumer, as well as the URL, Privacy Policy URL, and End User License Agreement (EULA) URL.

Once these fields are completed, saving the configuration will generate a Key and a Secret, which will be used to obtain the authentication token.

Token Retrieval

The URL for token retrieval is: https://one.fracttal.com/oauth/token

Client Credentials

When using this type of authorization, the token is obtained as follows:

curl -X POST -u "key:secret" https://one.fracttal.com/oauth/token -d grant_type=client_credentials

{
	"access_token":"******",
	"token_type":"Bearer",
	"expires_in":7200,
	"refresh_token":"***",
	"state":"client_credentials"
}

When executing the command, key and secret must be replaced with the values obtained when configuring the OAuth consumer.

Authorization Code

When using this type of authorization, the end user must first be prompted for authorization by redirecting their browser to the authorization URL: https://one.fracttal.com/oauth/authorize.

The return redirection (or callback) will include the query parameter ?code={authorization_code}, which will be required to obtain the token, as follows:

curl -X POST -u "key:secret" https://one.fracttal.com/oauth/token -d grant_type=authorization_code -d code={authorization_code}

{
  "access_token":"*****",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"***",
  "state":"authorization_code"
}

When executing the command, key and secret must be replaced with the values obtained when configuring the OAuth consumer in Fracttal One, and authorization_codee must be replaced with the code received in the callback from the previous step.

Sending Requests

Once an access token has been obtained, the recommended and most convenient way to include it in your requests is by sending it in the request header, as follows:

You must replace {access_token} with the actual access token value.

When including the token in the request header, it is important to use the “Bearer” authentication scheme to indicate that an access token is being sent. This ensures that the server can correctly identify and authenticate the request.

Token Refresh

When using the FRACTTAL API, it is important to note that access tokens have a duration of two hours and will expire after that period. When an access token expires, a response with status code 401 (Unauthorized) will be returned.

To facilitate the renewal of access tokens without requiring end-user intervention, access token grant responses include a refresh token in the “refresh_token” field. This refresh token can be used to request a new access token as follows:

curl -X POST -u "key:secret" https://one.fracttal.com/oauth/token -d grant_type=refresh_token -d refresh_token={token_refresh}

The value token_refresh must be replaced with the actual refresh token.

It is important to use the refresh token securely and ensure it is protected from unauthorized access, as its compromise could allow a third party to gain access to protected resources.