CyCognito Users API
The Users API from CyCognito — 2 operation(s) for users.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.0.1
title: CyCognito API V1 Reference Assets Users API
description: 'The CyCognito API V1 is a REST API that allows you to post and get data from our main data entities—assets and issues. You can also manage the scope of your attack surface, attribute assets to organizations, and verify the identity of IP scans on your assets. Our legacy API (V0) documentation is available for download [here](https://platform.cycognito.com/CyCognito-API-V0-Reference.pdf). While V0 is still being supported, please note that this API is undergoing deprecation.
| Code | Name | Description |
|------|------|-------------|
| 200 | OK | Success |
| 400 | Bad Request | The request is malformed—e.g., the body cannot be properly parsed, expected fields are not included in the body, or unsupported request header values. |
| 403 | Access Restricted | There are insufficient permissions or a valid API key was not provided. |
| 404 | Not Found | The provided resource was not found. |
| 405 | Method Not Allowed | The HTTP method is not allowed for the given resource. |
| 415 | Unsupported Media Type | The request content type is not supported. |
| 5XX | | Server failure | |
'
tags:
- name: Users
paths:
/v1/users:
get:
description: Get user data for all users registered in your CyCognito account.
security:
- apiAuth: []
summary: Get all user data
tags:
- Users
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
description: The user's full name.
type: string
example: Marty McFly
email:
description: The user's email address.
type: string
example: marty@acme.com
roles:
description: 'Indicates the user''s permission levels corresponding to their teams. In the following example, the user has IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":""viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
type: object
additionalProperties:
type: string
example: "{\n \"Team1\": \"it-user\",\n \"Team2\": \"admin\",\n \"\": \"viewer\"\n}"
activated:
description: Indicates whether or not the user has activated their account.
type: boolean
example: 'true'
invited-at:
description: Indicates the date and time at which the user received an invitation to the CyCognito platform.
anyOf:
- type: string
format: date-time
- type: 'null'
example: '2024-05-18T09:29:26.259Z'
invited-by:
description: The user who sent the invitation to the specified user.
type: string
example: Biff Tannen
last-login:
description: Indicates the date and time at which the user last signed in to the CyCognito platform.
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
example: 2024-05-20T10:31.368Z
required:
- name
- email
- roles
- activated
- invited-by
- last-login
post:
description: Create a new user.
security:
- apiAuth: []
summary: Create user
tags:
- Users
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
description: The full name of the new user.
type: string
example: Marty McFly
email:
description: The new user's email address.
type: string
example: marty@acme.com
roles:
description: 'Designates the new user''s permission levels corresponding to their teams. In the following example, the new user will have IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: `{"Team1": "it-user", "Team2":"admin", "":"viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
type: object
additionalProperties:
type: string
enum:
- viewer
- it-user
- admin
- analyst
- guest
example: "{\n \"Team1\": \"it-user\",\n \"Team2\": \"admin\",\n \"\": \"viewer\"\n}"
required:
- name
- email
- roles
responses:
'200':
content:
application/json:
schema:
type: object
properties:
status:
description: Indicates whether a new user was successfully added and an invitation was sent.
type: string
example: New user invitation was sent
required:
- status
/v1/users/{email}:
get:
description: Get user data for the specified individual user.
security:
- apiAuth: []
summary: Get individual user data
tags:
- Users
parameters:
- name: email
in: path
schema:
type: string
required: true
responses:
'200':
content:
application/json:
schema:
anyOf:
- type: object
properties:
name:
description: The user's full name.
type: string
example: Marty McFly
email:
description: The user's email address.
type: string
example: marty@acme.com
roles:
description: 'Indicates the user''s permission levels corresponding to their teams. In the following example, the user has IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":""viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
type: object
additionalProperties:
type: string
example: "{\n \"Team1\": \"it-user\",\n \"Team2\": \"admin\",\n \"\": \"viewer\"\n}"
activated:
description: Indicates whether or not the user has activated their account.
type: boolean
example: 'true'
invited-at:
description: Indicates the date and time at which the user received an invitation to the CyCognito platform.
type: string
format: date-time
example: '2024-05-18T09:29:26.259Z'
invited-by:
description: The user who sent the invitation to the specified user.
type: string
example: Biff Tannen
last-login:
description: Indicates the date and time at which the user last signed in to the CyCognito platform.
anyOf:
- type: string
format: date-time
- type: string
- type: 'null'
example: 2024-05-20T10:31.368Z
required:
- name
- email
- roles
- activated
- invited-at
- invited-by
- last-login
- type: string
put:
description: Edit single teams or roles for the specified user.
security:
- apiAuth: []
summary: Edit single user teams or roles
tags:
- Users
parameters:
- name: email
in: path
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
roles:
description: 'Designates the new user''s permission levels corresponding to their teams. In the following example, the new user will have IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":"viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
type: object
additionalProperties:
type: string
enum:
- viewer
- it-user
- admin
- analyst
- guest
example: "{\n \"Team1\": \"it-user\",\n \"Team2\": \"admin\",\n \"\": \"viewer\"\n}"
required:
- roles
responses:
'200':
content:
application/json:
schema:
type: object
properties:
status:
description: Indicates whether the user's role within the specified team was updated.
type: string
example: User was edited.
required:
- status
delete:
description: Remove a CyCognito user from the current team associated with <span name="kb-api-key-management-link">your API key</span>.
security:
- apiAuth: []
summary: Delete user
tags:
- Users
parameters:
- name: email
in: path
schema:
type: string
required: true
description: The email of the user who you want to remove from the current team associated with <span name="kb-api-key-management-link">your API key</span>.
responses:
'200':
content:
application/json:
schema:
type: object
properties:
status:
description: Indicates whether a user was successfully removed from the team.
type: string
example: User was deleted
required:
- status
components:
securitySchemes:
apiAuth:
type: apiKey
name: Authorization
in: header