Skip to main content

Authentication API

Description

This API generates a JWT (JSON Web Token) access token which is used for authentication with all Checkmarx One APIs.

Notice

The access token is valid for a 30 minute session.

There are two methods that can be used to generate an access token:

  • Refresh Token (API Key) - If you have a refresh token, you can submit that with this API in order to receive an access token. To learn how to generate a refresh token, see Generating a Refresh Token (API Key).

  • OAuth2 Client - If you have an OAuth2 Client for Checkmarx One, you can submit your Client ID and Secret with this API in order to receive an access token. To learn how to generate an OAuth2 Client, see Creating an Oauth2 Client.

    Notice

    The access token inherits whichever roles (permissions) are assigned to the OAuth2 Client.

Notice

In addition to returning an access token, this API also returns a new refresh token which can be used for future login requests.

Method

POST

Workflow

  1. Use the Authentication API to generate an access token

  2. Use the access token for authentication of all APIs

URL

  • US Environment - https://iam.checkmarx.net/auth/realms/{tenant_account_name}/protocol/openid-connect/token

  • EU Environment - https://eu.iam.checkmarx.net/auth/realms/{tenant_account_name}/protocol/openid-connect/token

Swagger

Curl Sample - Refresh Token

curl -X POST \{https://iam.checkmarx.net/auth/realms/{{TENANT_NAME}}/protocol/openid-connect/token \

--data "grant_type=refresh_token" \

--data "client_id=ast-app" \

--data "refresh_token={{Your_API_KEY}}"

Curl Sample - OAuth2 Client

curl --location --request POST 'https://eu.iam.checkmarx.net/auth/realms/{{TENANT_NAME}}/protocol/openid-connect/token ' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'Accept: application/json' \

--data-urlencode 'client_id={{your-iam-oauth-client}}' \

--data-urlencode 'grant_type=client_credentials' \

--data-urlencode 'client_secret={{secret_key}}'

Media Type (header)

Accept: application/json

Parameters

All Parameters are required (depending on the specified grant_type)

Parameter

Type

Enum

Description

grant_type

formdata

  • refresh_token - an API Key obtained from the Checkmarx One web portal or from a previous Authentication

  • client_credentials - use your OAuth2 ‘Client ID’ and 'Secret'

The type of authentication credentials submitted.

client_id (for grant_type “client_credentials”)

formdata

-

Your OAuth2 Client ID

client_secret (for grant_type “client_credentials”)

formdata

-

Your OAuth2 Secret

client_id

formdata

ast-app

Currently “ast-app” is the only supported ID.

refresh_token (for grant_type “refresh_token”)

formdata

-

The refresh token (i.e., API Key) that was generated for your account in the IAM.

Success Response

Code: 200 Authenticated

Attribute

Type

Description

access_token

string

The access token to be use for authentication with your Checkmarx One API calls.

expires_in

integer

Time left until the token expires (given in seconds).

Tokens are valid for 30 minutes.

refresh_expires_in

integer

The time period for which the newly generated refresh token is valid (given in seconds).

Tip

If the value returned is “0”, that indicates that it remains valid indefinitely.

refresh_token

string

Returns a new refresh token which can be used to generate new access tokens.

token_type

string

The type of authentication, e.g bearer.

not-before-policy

integer

The time delay until the access token is first activated (given in seconds).

Tip

If the value returned is “0”, that indicates that the access token is valid immediately.

session_state

string

A unique ID representing the session.

scope

string

The permissions associated with this access token.

Sample Success Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR...phQlk0nAGjOtvG8UT-8iaA",
    "expires_in": 1800,
    "refresh_expires_in": 0,
    "refresh_token": "eyJhbGciOiJIUzI1Ni...Pf43RbBz4M",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "f4308084-84b5-41af-a326-7c38d9fc19fa",
    "scope": "iam-api profile email ast-api groups offline_access roles"
}

Error Response