API v2: Secret Access Management 🆕

Overview

Secret access management tracks and controls who accesses secrets in collections. It provides audit trails, exclusive checkout capabilities, time-based access control, and the ability to mark accesses as safe for exposure monitoring.

Data Structures

SecretAccessModel

Attribute	Type	Required	Description
id	string		Read-only. Unique secret access identifier.
user_id	string	yes	Read-only. User identifier.
secret_id	string	yes	Read-only. Secret identifier.
secret_name	string		Read-only. Hidden; expensive to use. Secret name.
secret_removed	boolean		Read-only; expensive to use. Indicates whether the secret has been removed.
secret_history_id	string	yes	Read-only. Secret value version identifier.
collection_id	string	yes	Read-only; expensive to use. Collection identifier.
collection_name	string		Read-only. Hidden; expensive to use. Collection name.
collection_removed	boolean		Read-only; expensive to use. Indicates whether the collection has been removed.
source_ip	string		Read-only. Client IP address at checkout time.
source_port	number		Read-only. Client port at checkout time.
accessed_at	datetime	yes	Read-only. When the checkout started.
checked_in_at	datetime		Read-only. When user checked in.
expires_at	datetime		Read-only. When access was set to expire. Uses secret checkout_time_limit attribute.
exclusive	boolean	yes	Read-only. Whether this was an exclusive checkout that locks the secret. Uses secret checkout_exclusive attribute.
forced	boolean	yes	Read-only. Whether user forced checkout while another user had exclusive access.
user_name	string		Read-only; expensive to use. User name.
active	boolean	yes	Read-only; expensive to use. Whether the checkout is still active and can be checkin.
marked_safe	boolean		Read-only; expensive to use. Whether the this access was marked as safe.
marked_safe_by	string		Read-only. User ID who marked this access as safe.
marked_safe_by_name	string		Read-only; expensive to use. Name of the user who marked this access as safe.
marked_safe_at	datetime		Read-only. Timestamp when access was marked as safe.
user_blocked	boolean		Read-only; expensive to use. Indicates whether the user who accessed the secret is blocked.
user_removed	boolean		Read-only; expensive to use. Indicates whether the user who accessed the secret is removed.
user_lost_access	boolean		Read-only; expensive to use. Indicates whether the user who accessed the secret has lost access to the collection.
secret_exposed	boolean		Read-only. Hidden; expensive to use. Boolean sum of user_blocked, user_removed and user_lost_access fields.
created_at	datetime		Read-only. Timestamp of creation.
modified_at	datetime		Read-only. Timestamp of modification.
removed	boolean		Read-only.

Retrieve Available Attributes of the SecretAccessModel

Request

Method	GET
Path	/api/v2/objspec/secret_access

GET /api/v2/objspec/secret_access

Note

This endpoint may not be available if secret_access doesn’t have a separate object specification.

List Secret Access Records

Request

Method	GET
Path	/api/v2/secret/access

GET /api/v2/secret/access

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/secret/access'

Response

{
    "result": "success",
    "secret_access": [
        {
            "id": "1",
            "user_id": "8754997675608244225",
            "secret_id": "8754997675608244229",
            "secret_removed": false,
            "secret_history_id": "8754997675608244228",
            "collection_id": "8754997675608244227",
            "collection_removed": false,
            "source_ip": "10.2.0.182",
            "source_port": 55033,
            "accessed_at": "2026-04-02T23:56:21Z",
            "checked_in_at": "2026-04-02T23:56:21Z",
            "exclusive": false,
            "forced": false,
            "user_name": "admin",
            "active": false,
            "marked_safe": false,
            "user_blocked": false,
            "user_removed": false,
            "user_lost_access": false
        }
    ]
}

Get Secret Access for Specific Secret

Request

Method	GET
Path	/api/v2/secret/<secret_id>/access

GET /api/v2/secret/<secret_id>/access

Example Request

curl -s -k -X GET \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/secret/8754997675608244229/access'

Response

{
    "result": "success",
    "secret_access": [
        {
            "id": "1",
            "user_id": "8754997675608244225",
            "secret_id": "8754997675608244229",
            "secret_removed": false,
            "secret_history_id": "8754997675608244228",
            "collection_id": "8754997675608244227",
            "source_ip": "10.2.0.182",
            "source_port": 55033,
            "accessed_at": "2026-04-02T23:56:21Z",
            "checked_in_at": "2026-04-02T23:56:21Z",
            "exclusive": false,
            "forced": false,
            "user_name": "admin",
            "active": false,
            "marked_safe": false,
            "user_blocked": false,
            "user_removed": false,
            "user_lost_access": false
        }
    ]
}

Check In Secret Access

Request

Method	POST
Path	/api/v2/secret/access/<access_id>/checkin

POST /api/v2/secret/access/<access_id>/checkin

Example Request

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/secret/access/1/checkin'

Response

{
    "result": "success",
    "secret_access": [
        {
            "id": "1",
            "checked_in_at": "2026-04-02T23:56:21Z",
            "active": false
        }
    ]
}

Mark Secret as Safe

Request

Method	POST
Path	/api/v2/secret/<secret_id>/mark_safe

POST /api/v2/secret/<secret_id>/mark_safe

Example Request

curl -s -k -X POST \
  -H 'Authorization: <token>' \
  'https://10.31.135.179/api/v2/secret/8754997675608244229/mark_safe'

Response

{
    "result": "success"
}

Note

The mark_safe endpoint is used to mark a secret as safe after it has been reviewed for potential exposure. This updates the secret’s exposure status and clears any exposure alerts.