Used to authenticate with the API. Can be issued by org admins. Each access token is owned by the org that issued it. [](https://god.gw.postman.com/run-collection/9829310-0a2fce9d-f679-41e8-a438-bcf13ddec403?action=collection%2Ffork&collection-url=entityId%3D9829310-0a2fce9d-f679-41e8-a438-bcf13ddec403%26entityType%3Dcollection%26workspaceId%3Da63f69cc-5c31-4f2b-8d28-b647f83b9e97)
openapi: 3.0.0
info:
x-logo:
url: https://docs.shiftleft.io/img/sl-logo.svg
version: 4.0.0
title: alerting tokens API
description: 'The Qwiet API allows you to programmatically interact with Qwiet. You can manage users and their roles and get scan-related information, such as which applications were scanned and what vulnerabilities were identified by Qwiet as being present. You can also compare scans to see changes to your applications over time.
# Authentication
Use of the Qwiet API requires an access token, which is available via the [Qwiet UI](https://app.shiftleft.io/user/profile).
'
servers:
- url: https://app.shiftleft.io/api/v4
tags:
- name: tokens
x-displayName: Access tokens
description: 'Used to authenticate with the API.
Can be issued by org admins. Each access token is owned by the org that issued it.
[](https://god.gw.postman.com/run-collection/9829310-0a2fce9d-f679-41e8-a438-bcf13ddec403?action=collection%2Ffork&collection-url=entityId%3D9829310-0a2fce9d-f679-41e8-a438-bcf13ddec403%26entityType%3Dcollection%26workspaceId%3Da63f69cc-5c31-4f2b-8d28-b647f83b9e97)
'
paths:
/orgs/{orgID}/roles:
parameters:
- $ref: '#/components/parameters/orgID'
get:
tags:
- tokens
summary: List access token roles
operationId: ListRoles
description: 'Return a list of roles an that are assigned to an access token and are available for use (includes only the roles that are managed by Qwiet).
'
security:
- BearerToken:
- roles:list
parameters:
- $ref: '#/components/parameters/orgID'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- type: object
required:
- response
properties:
response:
type: array
items:
$ref: '#/components/schemas/Role'
example:
ok: true
response:
- id: 5b588f3a-7fe0-444d-afbb-c0d5ee04139b
label: Jira plugin
description: This role grants the token permissions required for the Qwiet Jira Plugin.
role_type: managed
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orgs/{orgID}/tokens:
parameters:
- $ref: '#/components/parameters/orgID'
get:
tags:
- tokens
summary: List tokens
operationId: ListTokens
description: '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 Qwiet issues the token.
'
security:
- BearerToken:
- tokens:list
parameters:
- name: show_expired
in: query
description: Whether expired tokens should be returned or not
schema:
type: boolean
- name: token_type
in: query
description: Filter the response by the type of token
schema:
$ref: '#/components/schemas/TokenType'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- type: object
required:
- response
properties:
response:
type: array
items:
$ref: '#/components/schemas/Token'
example:
ok: true
response:
- id: b7f521ca-d3f8-4a22-b7d9-8d12b1a7c1b7
label: Jira integration token
description: This token was generated to integrate the Qwiet Jira Plugin
role_id: 5b588f3a-7fe0-444d-afbb-c0d5ee04139b
token_type: integration
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
tags:
- tokens
summary: Create token
operationId: CreateToken
description: 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.
security:
- BearerToken:
- tokens:create
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewToken'
example:
label: On-prem Jira
description: Used by the on-prem Jira integration to communicate with Qwiet
role_id: 5b588f3a-7fe0-444d-afbb-c0d5ee04139b
token_type: integration
valid_for_seconds: 600
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessResponse'
- type: object
required:
- response
properties:
response:
$ref: '#/components/schemas/CreateOrgTokenResponse'
example:
ok: true
response:
value: this_is_the_token_value_that_will_only_be_exposed_once
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
label: On-prem Jira
token_type: integration
description: Used by the on-prem Jira integration to communicate with Qwiet
role_id: 5b588f3a-7fe0-444d-afbb-c0d5ee04139b
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/orgs/{orgID}/tokens/{tokenID}:
parameters:
- $ref: '#/components/parameters/orgID'
- name: tokenID
in: path
description: The token ID
required: true
schema:
type: string
format: uuid
delete:
tags:
- tokens
summary: Delete token
operationId: DeleteToken
description: Delete an access token using its identifier.
security:
- BearerToken:
- tokens:delete
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
orgID:
name: orgID
in: path
description: The org ID
required: true
schema:
type: string
format: uuid
schemas:
NewToken:
type: object
required:
- label
- role_id
properties:
label:
type: string
description: A user-defined label to identify the token
description:
type: string
description: A user-defined description that describes why this token was created and how it should be used
role_id:
type: string
description: The ID of the role attached to this token. For integration tokens, this can be either a predefined role ID from the <a href="/api/#operation/ListRoles">List access token roles</a> endpoint or a custom organization role ID from the <a href="/api/#operation/ListCustomRBACRoles">List custom RBAC roles</a> endpoint.
token_type:
$ref: '#/components/schemas/TokenType'
valid_for_seconds:
type: integer
description: The duration (in seconds) for which the token is valid (optional)
Error:
type: object
required:
- ok
- code
- message
properties:
ok:
type: boolean
description: Whether the request was successful (true) or not (false)
code:
type: string
description: The `enum` representing the error encountered
example: INTERNAL_SERVER_ERROR
message:
type: string
description: A message describing the error
example: Internal Server Error
validation_errors:
type: array
description: The validation errors the user should correct before re-submitting the request
items:
type: string
description: A description of the validation error
CreateOrgTokenResponse:
allOf:
- type: object
required:
- value
properties:
value:
type: string
description: The value of the token that will only be exposed once (and only in this API response)
- $ref: '#/components/schemas/Token'
Role:
allOf:
- type: object
required:
- id
properties:
id:
type: string
format: uuid
- $ref: '#/components/schemas/NewRole'
TokenType:
type: string
enum:
- access
- integration
SuccessResponse:
type: object
required:
- ok
properties:
ok:
type: boolean
description: Whether the request was successful or not
NewRole:
type: object
required:
- label
- description
properties:
label:
type: string
description: The user-defined label used to identify the token
description:
type: string
description: The user-defined description that describes why this role was created and how it should be used
role_type:
type: string
enum:
- managed
- org
description: "Whether this role is a managed role or an org role:\n - Managed roles are maintained by Qwiet\n - Org roles are created/maintained by a customer's organization admin\n"
Token:
allOf:
- type: object
required:
- id
properties:
id:
type: string
format: uuid
description: The ID of the token that can be used to delete the token
expires_at:
type: string
description: An expiry date for the token (optional)
- $ref: '#/components/schemas/NewToken'
securitySchemes:
BearerToken:
description: 'Use of the Qwiet API requires an access token, which is available via the Qwiet Dashboard (either under [Account Settings](https://app.shiftleft.io/user/profile) or [Integration Tokens](https://app.shiftleft.io/integrations)) or via the `/tokens` endpoints. You can pass an access token to the API using the HTTP `Authorization` Request header as follows:\
`Authorization: Bearer {access token}`
'
type: http
scheme: bearer