Censys Account Management API

openapi: 3.1.0
info:
  contact:
    email: support@censys.io
    name: Censys Support
  description: '# Asset Graph API


    The Asset Graph API provides comprehensive visibility into your Internet-facing assets. Use this API to build and manage attack surfaces by creating asset graphs, configuring seeds and exclusions, running discovery executions, and retrieving discovered assets and risk metadata.


    ### Authentication


    All requests must include a valid Censys personal access token (PAT) in the `Authorization` header:


    ```

    Authorization: Bearer <your-api-token>

    ```


    An `X-Organization-ID` header must also be present on every request. This identifies the Censys organization that owns the resources being accessed.


    ```

    X-Organization-ID: <your-organization-id>

    ```


    ### Core Concepts


    - **Asset Graph**: The parent resource representing an attack surface. Each asset graph contains seeds, excluded assets, and executions.

    - **Seeds**: Persistent starting points used to discover additional assets. Supported types include IP addresses, domains, CIDRs, ASNs, certificates, and web properties.

    - **Excluded Assets**: Assets explicitly excluded from the graph. Excluded assets will not appear in execution results and will not be used to discover additional assets.

    - **Executions**: A discovery process that uses the graph''s configured seeds and excluded assets to generate a complete snapshot of the attack surface. Censys periodically runs executions in the background, or they can be triggered on-demand.

    - **Assets**: Internet-facing resources discovered during an execution, including hosts, domains, certificates, and web properties. Each asset includes discovery paths showing how it was found from your seeds.

    - **Risks**: Vulnerabilities, exposures, misconfigurations, and threats identified on discovered assets.


    ### Getting Started


    1. **Create an asset graph** to represent your attack surface.

    2. **Add seeds** — the known assets that Censys will use as starting points for discovery.

    3. **Optionally add excluded assets** to omit specific assets from results.

    4. **Create an execution** to trigger the discovery process, or wait for Censys to run one automatically.

    5. **List assets** from a completed execution to view your discovered attack surface.

    6. **Look up risk metadata** for any risk IDs found on your assets.

    '
  title: Asset Graph Account Management API
  version: 1.0.12
servers:
- description: Asset Graph API
  url: https://graph.data.censys.io
tags:
- description: Endpoints related to the Account Management product
  name: Account Management
paths:
  /v3/accounts/organizations/{organization_id}:
    get:
      description: Retrieve an organization's details, including the count of organization members broken down by role and organization settings such as AI training and MFA requirements.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-org-details
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: Whether to include how many members are in this organization, split by role.
        explode: false
        in: query
        name: include_member_counts
        schema:
          default: false
          description: Whether to include how many members are in this organization, split by role.
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeOrganizationDetails'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Organization not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid organization ID
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Get Organization Details
      tags:
      - Account Management
      x-speakeasy-name-override: GetOrganizationDetails
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/audit-log-events:
    get:
      description: Retrieve audit log events for an organization. Use query parameters to filter events by time range, user, and event type.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-org-audit-log-events
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: Amount of events to return per page.
        example: 1
        explode: false
        in: query
        name: page_size
        schema:
          default: 10
          description: Amount of events to return per page.
          examples:
          - 1
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      - description: Page token for the requested page of audit log events.
        explode: false
        in: query
        name: page_token
        schema:
          description: Page token for the requested page of audit log events.
          type: string
      - description: Only return events that occurred after this time. This value must be on or after 2026-01-01T00:00:00Z. If not provided, will default to the earliest possible date.
        example: '2026-01-01T00:00:00Z'
        explode: false
        in: query
        name: start_time
        schema:
          description: Only return events that occurred after this time. This value must be on or after 2026-01-01T00:00:00Z. If not provided, will default to the earliest possible date.
          examples:
          - '2026-01-01T00:00:00Z'
          format: date-time
          type: string
      - description: Only return events that occurred before this time. This value must not be in the future. If not provided, it defaults to the current time.
        example: '2026-02-01T00:00:00Z'
        explode: false
        in: query
        name: end_time
        schema:
          description: Only return events that occurred before this time. This value must not be in the future. If not provided, it defaults to the current time.
          examples:
          - '2026-02-01T00:00:00Z'
          format: date-time
          type: string
      - description: Only return events of this type. This field is deprecated and will be removed in a future version. Use event_types instead.
        explode: false
        in: query
        name: event_type
        schema:
          deprecated: true
          description: Only return events of this type. This field is deprecated and will be removed in a future version. Use event_types instead.
          enum:
          - user_created
          - user_login
          - user_login_failed
          - user_password_changed
          - user_password_reset
          - user_mfa_changed
          - user_settings_changed
          - user_enabled
          - user_disabled
          - invitation_created
          - invitation_resent
          - invitation_accepted
          - invitation_deleted
          - membership_created
          - membership_updated
          - membership_removed
          - org_created
          - org_updated
          - org_deleted
          - saml_config_created
          - saml_config_updated
          - saml_config_deleted
          - saml_config_domain_verified
          - pat_created
          - pat_deleted
          - global_data_search_executed
          - global_data_lookup_executed
          - global_data_aggregation_executed
          - asm_seed_created
          - asm_seed_deleted
          - asm_exclude_created
          - asm_exclude_deleted
          - asm_risk_instance_severity_changed
          - asm_risk_instance_accepted
          - asm_risk_instance_unaccepted
          - asm_risk_type_severity_changed
          - asm_risk_type_enabled
          - asm_risk_type_disabled
          - asm_risk_type_default_enabled
          - tag_created
          - tag_updated
          - tag_deleted
          - tag_assigned
          - tag_unassigned
          - tag_bulk_operation_started
          - tag_bulk_operation_completed
          - tag_bulk_operation_cancelled
          - comment_created
          - comment_updated
          - comment_deleted
          type: string
      - description: Only return events of these types.
        example:
        - user_login
        - pat_created
        explode: false
        in: query
        name: event_types
        schema:
          description: Only return events of these types.
          examples:
          - - user_login
            - pat_created
          items:
            enum:
            - user_created
            - user_login
            - user_login_failed
            - user_password_changed
            - user_password_reset
            - user_mfa_changed
            - user_settings_changed
            - user_enabled
            - user_disabled
            - invitation_created
            - invitation_resent
            - invitation_accepted
            - invitation_deleted
            - membership_created
            - membership_updated
            - membership_removed
            - org_created
            - org_updated
            - org_deleted
            - saml_config_created
            - saml_config_updated
            - saml_config_deleted
            - saml_config_domain_verified
            - pat_created
            - pat_deleted
            - global_data_search_executed
            - global_data_lookup_executed
            - global_data_aggregation_executed
            - asm_seed_created
            - asm_seed_deleted
            - asm_exclude_created
            - asm_exclude_deleted
            - asm_risk_instance_severity_changed
            - asm_risk_instance_accepted
            - asm_risk_instance_unaccepted
            - asm_risk_type_severity_changed
            - asm_risk_type_enabled
            - asm_risk_type_disabled
            - asm_risk_type_default_enabled
            - tag_created
            - tag_updated
            - tag_deleted
            - tag_assigned
            - tag_unassigned
            - tag_bulk_operation_started
            - tag_bulk_operation_completed
            - tag_bulk_operation_cancelled
            - comment_created
            - comment_updated
            - comment_deleted
            type: string
          maxItems: 10
          type:
          - array
          - 'null'
      - description: Exclude events of these types.
        example:
        - user_login
        - pat_created
        explode: false
        in: query
        name: exclude_event_types
        schema:
          description: Exclude events of these types.
          examples:
          - - user_login
            - pat_created
          items:
            enum:
            - user_created
            - user_login
            - user_login_failed
            - user_password_changed
            - user_password_reset
            - user_mfa_changed
            - user_settings_changed
            - user_enabled
            - user_disabled
            - invitation_created
            - invitation_resent
            - invitation_accepted
            - invitation_deleted
            - membership_created
            - membership_updated
            - membership_removed
            - org_created
            - org_updated
            - org_deleted
            - saml_config_created
            - saml_config_updated
            - saml_config_deleted
            - saml_config_domain_verified
            - pat_created
            - pat_deleted
            - global_data_search_executed
            - global_data_lookup_executed
            - global_data_aggregation_executed
            - asm_seed_created
            - asm_seed_deleted
            - asm_exclude_created
            - asm_exclude_deleted
            - asm_risk_instance_severity_changed
            - asm_risk_instance_accepted
            - asm_risk_instance_unaccepted
            - asm_risk_type_severity_changed
            - asm_risk_type_enabled
            - asm_risk_type_disabled
            - asm_risk_type_default_enabled
            - tag_created
            - tag_updated
            - tag_deleted
            - tag_assigned
            - tag_unassigned
            - tag_bulk_operation_started
            - tag_bulk_operation_completed
            - tag_bulk_operation_cancelled
            - comment_created
            - comment_updated
            - comment_deleted
            type: string
          maxItems: 10
          type:
          - array
          - 'null'
      - description: Only return events performed by this user.
        example: user@example.com
        explode: false
        in: query
        name: user_email
        schema:
          description: Only return events performed by this user.
          examples:
          - user@example.com
          type: string
      - description: Order events by this field.
        explode: false
        in: query
        name: order_by
        schema:
          default: timestamp_desc
          description: Order events by this field.
          enum:
          - timestamp_desc
          - timestamp_asc
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeAuditLogEventsResponse'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid request parameters
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys List Audit Log Events
      tags:
      - Account Management
      x-speakeasy-ignore: true
      x-speakeasy-name-override: GetOrganizationAuditLogEvents
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/credits:
    get:
      description: Retrieve credit balance and expiration information for an organization. <br><br>Credits expire 12 months after they are acquired.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-org-credits
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeOrganizationCredits'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Organization not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid organization ID
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Get Organization Credit Balance
      tags:
      - Account Management
      x-speakeasy-name-override: GetOrganizationCredits
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/credits/usage:
    get:
      description: Retrieve credit information for an organization over a specific date range. You must include a start date in your request.<br><br>Admins can obtain credit usage information for all users in their organization. Members may only retrieve usage information for their own account.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-org-credits-usage
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: The date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-06). This field is deprecated and will be removed in a future version. Use start_date and end_date instead. The date must be on or after 2025-01-01 (the earliest date available for credit usage reports).
        example: '2025-11-01'
        explode: false
        in: query
        name: date
        schema:
          deprecated: true
          description: The date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-06). This field is deprecated and will be removed in a future version. Use start_date and end_date instead. The date must be on or after 2025-01-01 (the earliest date available for credit usage reports).
          examples:
          - '2025-11-01'
          type: string
      - description: The start date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-01). Must be on or after 2025-01-01 (the earliest date available for credit usage reports).
        example: '2025-11-01'
        explode: false
        in: query
        name: start_date
        schema:
          description: The start date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-01). Must be on or after 2025-01-01 (the earliest date available for credit usage reports).
          examples:
          - '2025-11-01'
          format: date
          type: string
      - description: The end date for the credit usage report in YYYY-MM-DD format (e.g., 2025-12-01). If omitted, will default to today's date. The date range (end_date - start_date) cannot exceed 365 days (1 year).
        example: '2025-12-01'
        explode: false
        in: query
        name: end_date
        schema:
          description: The end date for the credit usage report in YYYY-MM-DD format (e.g., 2025-12-01). If omitted, will default to today's date. The date range (end_date - start_date) cannot exceed 365 days (1 year).
          examples:
          - '2025-12-01'
          format: date
          type: string
      - description: Whether to break down credit usage on a daily or monthly basis.
        example: daily
        explode: false
        in: query
        name: granularity
        required: true
        schema:
          default: daily
          description: Whether to break down credit usage on a daily or monthly basis.
          enum:
          - daily
          - monthly
          examples:
          - daily
          type: string
      - description: Whether to include a breakdown of individual users' consumption in the credit usage report.
        explode: false
        in: query
        name: include_consumer_breakdown
        schema:
          default: false
          description: Whether to include a breakdown of individual users' consumption in the credit usage report.
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCreditUsageReport'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid date format
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Organization not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid organization ID or date
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Get Organization Credit Usage
      tags:
      - Account Management
      x-speakeasy-name-override: GetOrganizationCreditUsage
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/invitations:
    post:
      description: Invite a user to an organization. The user will receive an email to join the organization. This is equivalent to [adding a new member via the UI](https://docs.censys.com/docs/platform-org-management#invite-members).<br><br>Only users with the Admin role in the provided organization can perform this operation.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-invite-user-to-org
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteMemberInputBody'
        required: true
      responses:
        '201':
          description: Invitation sent successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission or organization has reached maximum seat capacity
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Organization not found
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User is already a member of this organization or an invitation already exists
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid email address
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Invite User to Organization
      tags:
      - Account Management
      x-speakeasy-name-override: InviteUserToOrganization
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/members:
    get:
      description: Retrieve a paginated list of an organization's members and their user details, including their user ID, email, name, creation time, and roles.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-accountmanagement-list-org-members
      parameters:
      - description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: Number of members to return per page
        explode: false
        in: query
        name: page_size
        schema:
          default: 10
          description: Number of members to return per page
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      - description: Pagination token for retrieving the next page of results
        explode: false
        in: query
        name: page_token
        schema:
          description: Pagination token for retrieving the next page of results
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeOrganizationMembersList'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Organization not found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid input
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys List Organization Members
      tags:
      - Account Management
      x-speakeasy-name-override: ListOrganizationMembers
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/accounts/organizations/{organization_id}/members/{user_id}:
    delete:
      description: Remove a user from an organization. This is equivalent to [removing a member via the UI](https://docs.censys.com/docs/platform-org-management#rem

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/openapi/censys-account-management-api-openapi.yml