Working with the ShiftLeft API's tokens endpoints

This article walks you through using the token-related endpoints available via the ShiftLeft API.

We offer a Postman Collection that includes these endpoints; the relevant section of the Collection is called Tokens. We suggest creating an environment to store frequently used variables (including your ShiftLeft access token and org ID values).

Before proceeding, you should have…

Your access token and org ID values (both are available in the ShiftLeft Dashboard).

Authentication

The ShiftLeft API uses bearer authentication, which means that you must pass in a bearer token before you make calls to any of the endpoints. More specifically, you must provide your ShiftLeft access token in the HTTP Authorization request header before proceeding.

Get organization roles

Return a list of roles an org has available to use (includes only the roles that ShiftLeft manages).

curl GET \
'https://app.shiftleft.io/api/v4/orgs/{orgId}/roles' \
--header 'Authorization: Bearer {accessToken}'

Sample response:

{
"ok": true,
"response": [
{
"id": "66…35",
"role_type": "managed",
"label": "CI Token",
"description": "Grants permissions required to invoke the ShiftLeft CLI"
}
]
}

Get tokens

Return a list of tokens issued by the org. The token data returned includes metadata that identifies a token, included permissions, and an ID you can use to delete/revoke the token. The token data does NOT return the token value, which is exposed only when ShiftLeft issues the token.

curl GET \
'https://app.shiftleft.io/api/v4/orgs/{orgId}/tokens?show_expired={true|false} \
--header 'Authorization: Bearer {accessToken}'

Sample response:

{
"ok": true,
"response": [
{
"id": "76…eab",
"label": "Jira",
"description": "For Jira integration",
"role_id": "5b…39b"
}
]
}

Create token

Create a new token for use with the API. The token can be assigned a role using the role_id parameter in the request body. Obtain the role_id using the GET organization role endpoint.

curl POST \
https://app.shiftleft.io/api/v4/orgs/{orgID}/tokens' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
--data-raw '{
"label": "tokenName",
"description": "A description of the token",
"role_id": "The role ID to assign",
"token_type": "access or integration",
"valid_for_seconds": 600
}'

Sample response:

{
"ok": true,
"response": {
"id": "e83…abfd",
"label": "tokenName",
"description": "A description of the token",
"value": "eyJ...BVw"
}
}

Delete token

Delete an access token using its identifier.

curl -g DELETE \
'https://app.shiftleft.io/api/v4/orgs/{orgID}/tokens/{tokenID}' \
--header 'Authorization: Bearer {accessToken}'

Sample response:

{
"ok": true
}