API Reference

OAuth 2.0 Authentication

For OAuth App Integration, Pactima supports the OAuth 2.0 authorization code flow, allowing developers to create OAuth client apps and integrate Pactima with their own applications.

Overview

The OAuth authorization code flow enables third-party applications to obtain access tokens on behalf of users. It involves the following steps:

  1. The user is redirected to the Pactima authorization server https://pactima.com/oauth/authorize endpoint.
  2. The user authenticates and grants permission to the client app.
  3. The authorization server redirects the user back to the client app with an authorization code.
  4. The client app exchanges the authorization code for an access token by making a request to the https://rest.api.pactima.com/v1/oauth/actions/obtain-token endpoint.
  5. The client app uses the access token to make authenticated requests to Pactima's API endpoints.

Creating an OAuth Client App

To get started, you need to create an OAuth client app in Pactima. Follow these steps:

  1. Log in to your Pactima account and navigate to the Developer Console.
  2. Click on the "Create New App" button.
  3. Provide a name for your app and fill in the required details:
    • Redirect URIs: Specify the URIs where the authorization server will redirect the user after authentication. You can add multiple redirect URIs.
    • Scopes: Define the scopes that your app requires access to. Scopes determine the permissions and access levels of your app.
  4. Submit the form to create your OAuth client app.

After creation, you will receive a client ID and client secret. Keep the client secret secure and never share it publicly.

OAuth Authorization Request

To initiate the OAuth authorization flow, redirect the user to the https://pactima.com/oauth/authorize endpoint with the following query parameters:

  • clientId (required): The client ID of your OAuth client app.
  • redirectUri (required): The redirect URI where the authorization server will send the authorization code.
  • scope (optional): The requested scope(s) of the authorization.
  • state (recommended): An opaque value used by the client app to maintain state between the request and callback. It should be used to prevent CSRF attacks.

OAuth Token Request

After the user grants permission, the authorization server will redirect the user back to your specified redirect URI with an authorization code. Exchange this code for an access token by making a POST request to the https://rest.api.pactima.com/v1/oauth/actions/obtain-token endpoint with the following parameters:

  • code (required): The authorization code received from the authorization server.
  • clientId (required): The client ID of your OAuth client app.
  • clientSecret (required): The client secret of your OAuth client app.
  • redirectUri (required): The redirect URI used in the authorization request.
  • grantType (required): The grant type being used, which should be set to AUTHORIZATION_CODE for the authorization code flow.

Example token request:

POST https://rest.api.pactima.com/v1/oauth/actions/obtain-token
Content-Type: application/json

{
  "code": "YOUR_AUTHORIZATION_CODE",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "redirectUri": "YOUR_REDIRECT_URI",
  "grantType": "AUTHORIZATION_CODE"
}

OAuth Token Response

If the token request is successful, the authorization server will respond with a JSON object containing the following fields:

  • accessToken: The access token issued by the authorization server.
  • tokenType: The type of the token, typically set to Bearer.
  • expiresIn: The lifetime in seconds of the access token.
  • refreshToken: The refresh token, which can be used to obtain new access tokens when the current one expires.
  • scope: The scope of the access token.

Example token response:

{
  "accessToken": "YOUR_ACCESS_TOKEN",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshToken": "YOUR_REFRESH_TOKEN",
  "scope": "YOUR_SCOPE"
}

Using the Access Token

Once you have obtained an access token, you can use it to make authenticated requests to Pactima's API endpoints. Include the access token in the Authorization header of your requests using the Bearer token type.

Example authenticated request:

GET /api/resource
Authorization: Bearer YOUR_ACCESS_TOKEN

Refreshing Access Tokens

Access tokens have an expiration time. When an access token expires, you can use the refresh token to obtain a new access token without requiring the user to re-authenticate. To refresh an access token, make a POST request to the https://rest.api.pactima.com/v1/oauth/actions/obtain-token endpoint with the following parameters:

  • refreshToken (required): The refresh token obtained from the initial token response.
  • clientId (required): The client ID of your OAuth client app.
  • clientSecret (required): The client secret of your OAuth client app.
  • grantType (required): The grant type, which should be set to REFRESH_TOKEN for refreshing access tokens.

Example refresh token request:

POST https://rest.api.pactima.com/v1/oauth/actions/obtain-token
Content-Type: application/json

{
  "refreshToken": "YOUR_REFRESH_TOKEN",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "grantType": "REFRESH_TOKEN"
}

The authorization server will respond with a new access token and refresh token.