Virtual HSM
Home
  • Virtual HSM
  • Documentation
    • What is Virtual HSM?
    • Use Case: Attested Secret Provisioning in the Cloud
    • Setup
      • Install
      • vHSM Server Configuration
        • Parameters
        • vHSM Telemetry Parameters
      • vHSM Agent
        • Agent Configuration
      • vHSM Proxy
        • Proxy Configuration
    • Get Started
      • Start the Vault server
      • MariaDB root admin password provisioning on Azure DCXas_v5 VM
    • Supported Cloud Configurations
  • Tutorials
    • Deploying the vhsm Container on an EC2 Instance
    • CLI quickstart
    • vHSM Agent quickstart
    • vHSM Proxy quickstart
    • Passing vHSM secrets using ConfigMaps
    • Provisioning MariaDB Password on Azure DCXas_v5 VM
    • Registering a buckypaper plugin
    • Monitoring vHSM with Grafana
  • Integration with Utimaco SecurityServer
    • Integrate enclaive vHSM with Utimaco HSM
  • API
    • Auth
    • Default
    • Secrets
    • System
    • Identity
    • Models
  • vHSM CLI
    • Server and Infrastructure Management
      • vhsm server
      • vhsm proxy
      • vhsm monitor
      • vhsm status
      • vhsm agent
    • Secret Management
      • vhsm read
      • vhsm write
      • vhsm delete
      • vhsm list
      • vhsm secrets
        • vhsm secrets enable
        • vhsm secrets disable
        • vhsm secrets list
        • vhsm secrets move
        • vhsm secrets tune
      • vhsm unwrap
    • Configuration and Management
      • vhsm plugin
        • vhsm plugin info
        • vhsm plugin deregister
        • vhsm plugin list
        • vhsm plugin register
        • vhsm plugin reload
        • vhsm plugin reload-status
      • vhsm namespace
      • vhsm operator
      • vhsm print
      • vhsm path-help
      • vhsm lease
    • Auditing and Debugging
      • vhsm audit
      • vhsm debug
    • Attestation
    • Security and Encryption
      • vhsm pki
        • vhsm pki health-check
        • vhsm pki issue
        • vhsm pki list-intermediates
        • vhsm pki reissue
        • vhsm pki verify-sign
      • vhsm transit
      • vhsm ssh
      • vhsm transform
    • Authentication and Authorization
      • vhsm login
      • vhsm auth
      • vhsm token
      • vhsm policy
    • Storage and Data Mangement
      • vhsm kv
      • vhsm patch
    • vhsm version
      • vhsm version-history
  • Troubleshooting
    • CA Validity Period
    • CRL Validity Period
    • Root Certificate Issued Non-CA Leaves
    • Role Allows Implicit Localhost Issuance
    • Role Allows Glob-Based Wildcard Issuance
    • Performance Impact
    • Accessibility of Audit Information
    • Allow If-Modified-Since Requests
    • Auto-Tidy Disabled
    • Tidy Hasn't Run
    • Too Many Certificates
    • Enable ACME Issuance
    • ACME Response Headers Configuration
  • Resources
    • Community
    • GitHub
    • Youtube
    • CCx101 wiki
Powered by GitBook
On this page

Was this helpful?

  1. API

Auth

PreviousAPINextDefault

Was this helpful?

Lookup a token (Self)

get

Returns detailed information about the currently authenticated client token. This endpoint requires the caller to include a valid Vault token.

Responses
200
Token self-lookup successful
application/json
Responseany
403
Forbidden – The client token is invalid or lacks access
application/json
get
GET /v1/auth/token/lookup-self HTTP/1.1
Host: localhost:8200
Accept: */*
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2764790
  }
}

List token roles

get

Lists the token roles configured in the token auth backend. Requires a token with list capability. This is equivalent to Vault's LIST method.

Responses
200
A list of token roles
application/json
400
Bad request – malformed token or missing authentication
application/json
403
Forbidden – token does not have permission to list roles
application/json
get
GET /v1/auth/token/roles HTTP/1.1
Host: localhost:8200
Accept: */*
{
  "data": {
    "keys": [
      "role1",
      "role2"
    ]
  }
}

Read a token role

get

Retrieves the configuration of the specified token role.

Path parameters
role_namestringRequired

Name of the token role

Responses
200
Token role data retrieved successfully
application/json
404
Role not found
application/json
get
GET /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Accept: */*
{
  "data": {
    "allowed_policies": [
      "dev"
    ],
    "orphan": false,
    "renewable": true,
    "allowed_entity_aliases": [
      "web-entity-alias",
      "app-entity-*"
    ],
    "token_bound_cidrs": [
      "127.0.0.1/32",
      "128.252.0.0/16"
    ]
  }
}

Delete a token role

delete

Deletes the specified token role configuration.

Path parameters
role_namestringRequired

Name of the token role

Responses
204
Role deleted successfully. No content is returned.
403
Permission denied
application/json
404
Role not found
application/json
delete
DELETE /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Tidy token store

post

Performs maintenance to clean up invalid entries in the token store. This operation reads all accessors, tokens, and secondary index entries to identify and remove invalid tokens, orphaned children, and unused cubbyholes. Use with caution due to potential memory and I/O load.

Responses
200
Tidy operation started successfully.
application/json
403
Permission denied to perform tidy operation.
application/json
500
Internal server error while attempting to start tidy.
application/json
post
POST /v1/auth/token/tidy HTTP/1.1
Host: localhost:8200
Accept: */*
{
  "request_id": "84437c7f-36a1-6c1d-381d-14ec99217e94",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": [
    "Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs."
  ],
  "auth": null
}
  • GETList token accessors
  • POSTCreate a new orphan token
  • POSTCreate token with role
  • POSTLookup a token
  • POSTLookup a token (Accessor)
  • GETLookup a token (Self)
  • POSTRenew a token (Accessor)
  • POSTRenew a token (Self)
  • POSTRevoke a token
  • POSTRevoke a token accessor
  • POSTRevoke a token without revoking child tokens
  • POSTRevoke the calling token
  • GETList token roles
  • GETRead a token role
  • POSTCreate or update a token role
  • DELETEDelete a token role
  • POSTTidy token store

List token accessors

get

Returns a list of token accessor IDs which can then be used to discover their properties or revoke them. Requires both list and sudo capabilities on the auth/token/accessors path.

Query parameters
liststring · enumRequired

Must be set to "true"

Possible values:
Responses
200
A list of token accessor IDs.
application/json
403
Forbidden – caller lacks required capabilities (`list` and `sudo`).
application/json
400'
Bad Request – likely due to missing or incorrect query parameters.
application/json
get
GET /v1/auth/token/accessors HTTP/1.1
Host: localhost:8200
Accept: */*
{
  "keys": [
    "ac7d50e0-a67f-4b56-a04d-69f2e06e6e2e",
    "31bb5c18-795b-482d-8bcb-889c1aa7a5f9"
  ]
}

Create a new orphan token

post

Creates an orphan token that is not tied to a parent token. Orphan tokens do not expire when the parent token expires and are not revoked when the parent is revoked.

Body
idstringOptional

Custom client token ID (root only). Cannot contain "." or start with "s.".

role_namestringOptional

Name of the token role.

policiesstring[]Optional

Policies to assign to the token.

no_parentbooleanOptional

If true, creates an orphan token. Requires root or sudo.

Default: false
no_default_policybooleanOptional

If true, excludes the default policy.

Default: false
renewablebooleanOptional

Whether the token can be renewed.

Default: true
leasestringOptionalDeprecated

Deprecated. Use ttl instead.

ttlstringOptional

TTL (e.g., "1h").

typestring · enumOptional

Token type.

Possible values:
explicit_max_ttlstringOptional

Explicit max TTL that cannot be exceeded.

display_namestringOptional

Display name for the token.

Default: token
num_usesintegerOptional

Max number of uses. 0 means unlimited.

Default: 0
periodstringOptional

Periodic renewal interval. Requires root or sudo.

entity_aliasstringOptional

Entity alias to associate with (must be allowed in role).

Responses
200
Token successfully created
application/json
400
Bad Request – Invalid or missing input fields
application/json
403
Forbidden – The caller lacks permission to create orphan tokens
application/json
post
POST /v1/auth/token/create-orphan HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "policies": [
    "web",
    "stage"
  ],
  "meta": {
    "user": "armon"
  },
  "ttl": "1h",
  "renewable": true
}
{
  "request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1",
  "lease_id": "",
  "renewable": true,
  "lease_duration": 3600,
  "data": null,
  "wrap_info": null,
  "warnings": [],
  "auth": {
    "client_token": "s.abcde12345fghij67890",
    "accessor": "B6oixijqmeR4bsLOJH88Ska9",
    "policies": [
      "default"
    ],
    "token_policies": [
      "default"
    ],
    "metadata": {
      "user": "example"
    },
    "lease_duration": 3600,
    "renewable": true,
    "entity_id": "",
    "token_type": "service",
    "orphan": true,
    "num_uses": 1
  }
}

Create token with role

post

Creates a new token using the configuration of the specified role. The role may override parameters passed in the request body.

Path parameters
role_namestringRequired

The name of the token role to use for token creation.

Body
display_namestringOptional

Name to associate with this token

entity_aliasstringOptional

Name of the entity alias to associate with this token

explicit_max_ttlstringOptional

Explicit Max TTL of this token

idstringOptional

Value for the token

leasestringOptionalDeprecated

Use 'ttl' instead

metaobject · kvpairsOptional

Arbitrary key=value metadata to associate with the token

no_default_policybooleanOptional

Do not include default policy for this token

no_parentbooleanOptional

Create the token with no parent

num_usesintegerOptional

Max number of uses for this token

periodstringOptional

Renew period

policiesstring[]Optional

List of policies for the token

renewablebooleanOptional

Allow token to be renewed past its initial TTL up to system/mount maximum TTL

Default: true
ttlstringOptional

Time to live for this token

typestringOptional

Token type

Responses
200
Token successfully created
application/json
400
Bad Request – Invalid input or missing required fields
application/json
403
Forbidden – Insufficient privileges to create token with specified parameters
application/json
post
POST /v1/auth/token/create/{role_name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "display_name": "text",
  "entity_alias": "text",
  "explicit_max_ttl": "text",
  "id": "text",
  "meta": {},
  "no_default_policy": true,
  "no_parent": true,
  "num_uses": 1,
  "period": "text",
  "policies": [
    "text"
  ],
  "renewable": true,
  "ttl": "text",
  "type": "text"
}
{
  "auth": {
    "client_token": "s.1234567890abcdef",
    "policies": [
      "default",
      "web",
      "dev"
    ],
    "lease_duration": 3600,
    "renewable": true,
    "token_type": "service",
    "orphan": false
  }
}

Lookup a token

post

Returns detailed information about the specified client token. This endpoint requires a token with sufficient capabilities to perform lookups.

Body
anyOptional
Responses
200
Token lookup successful
application/json
400
Bad Request – Missing or malformed token field
application/json
403
Forbidden – Insufficient permissions to look up this token
application/json
post
POST /v1/auth/token/lookup HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2764790
  }
}

Lookup a token (Accessor)

post

Returns detailed information about a token using its accessor. This endpoint requires a token with sufficient capabilities to perform lookups.

Body
anyOptional
Responses
200
Token lookup by accessor successful
application/json
Responseany
400
Bad Request – Missing or malformed accessor field
application/json
403
Forbidden – Insufficient permissions to perform accessor lookup
application/json
post
POST /v1/auth/token/lookup-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed"
}
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2763902
  }
}

Renew a token (Accessor)

post

Renews a lease associated with a token using its accessor. This is used to prevent expiration and automatic revocation of the token. The token must be renewable and have an active lease.

Body
accessorstringOptional

Accessor of the token to renew (request body)

incrementinteger · secondsOptional

The desired increment in seconds to the token expiration

Default: 0
Responses
200
Token successfully renewed
application/json
Responseany
400
Bad Request – Missing or invalid accessor or token not renewable
application/json
403
Forbidden – Caller lacks permission to renew the token
application/json
post
POST /v1/auth/token/renew-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "accessor": "7JFKXuXKXa2D44YfDiovZ9aq"
}
{
  "auth": {
    "client_token": "",
    "policies": [
      "web",
      "stage"
    ],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

Renew a token (Self)

post

Renews a lease associated with the calling token. This prevents the token from expiring and being automatically revoked. Renewal is only possible if the token is renewable and has an active lease.

Body
incrementinteger · secondsOptional

The desired increment in seconds to the token expiration

Default: 0
tokenstringOptional

Token to renew (unused, does not need to be set)

Responses
200
Token successfully renewed
application/json
Responseany
403
Forbidden – Token is not renewable or not authorized
application/json
post
POST /v1/auth/token/renew-self HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "increment": "1h"
}
{
  "auth": {
    "client_token": "ABCD",
    "policies": [
      "web",
      "stage"
    ],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

Revoke a token

post

Revokes the specified token and all child tokens derived from it. Any dynamic secrets associated with the token are also revoked.

Body
tokenstringRequired

Token to revoke

Responses
204
Token successfully revoked. No content returned.
400
Invalid input or missing token.
application/json
403
Forbidden – the client token does not have permission to revoke the specified token.
application/json
post
POST /v1/auth/token/revoke HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "token": "ClientToken"
}

No content

Revoke a token accessor

post

Revokes the token associated with the specified accessor and all of its child tokens. This operation is useful in scenarios where the token ID is unavailable.

Body
accessorstringRequired

Accessor of the token to revoke

Responses
204
Token and its children successfully revoked. No content returned.
400
Invalid accessor or input data.
application/json
403
Forbidden – the client token does not have permission to revoke the specified accessor.
application/json
post
POST /v1/auth/token/revoke-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}

No content

Revoke a token without revoking child tokens

post

Revokes the specified token and all secrets created with it, but does not revoke child tokens. The child tokens become orphaned and can be revoked later using /auth/token/revoke. This operation requires root-level privileges.

Body
tokenstringRequired

Token to revoke

Responses
204
Token successfully revoked. No content returned.
400
Invalid token or malformed input.
application/json
403
Forbidden – the client token does not have permission to revoke this token.
application/json
post
POST /v1/auth/token/revoke-orphan HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "token": "ClientToken"
}

No content

Revoke the calling token

post

Revokes the token used to authenticate this request, along with all child tokens. All secrets generated with the token are also revoked.

Body
objectOptional
Responses
204
Token successfully revoked. No content returned.
400
Invalid request or the token cannot be revoked.
application/json
403
Forbidden – the token does not have permission to revoke itself.
application/json
post
POST /v1/auth/token/revoke-self HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Create or update a token role

post

Creates or replaces the specified token role configuration.

Path parameters
role_namestringRequired

Name of the token role

Body
allowed_entity_aliasesstring[]Optional

String or JSON list of allowed entity aliases. If set, specifies the entity aliases which are allowed to be used during token generation. This field supports globbing.

allowed_policiesstring[]Optional

If set, tokens can be created with any subset of the policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy names.

allowed_policies_globstring[]Optional

If set, tokens can be created with any subset of glob matched policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy name globs.

bound_cidrsstring[]OptionalDeprecated

Use 'token_bound_cidrs' instead.

disallowed_policiesstring[]Optional

If set, successful token creation via this role will require that no policies in the given list are requested. The parameter is a comma-delimited string of policy names.

disallowed_policies_globstring[]Optional

If set, successful token creation via this role will require that no requested policies glob match any of policies in this list. The parameter is a comma-delimited string of policy name globs.

explicit_max_ttlinteger · secondsOptionalDeprecated

Use 'token_explicit_max_ttl' instead.

orphanbooleanOptional

If true, tokens created via this role will be orphan tokens (have no parent)

path_suffixstringOptional

If set, tokens created via this role will contain the given suffix as a part of their path. This can be used to assist use of the 'revoke-prefix' endpoint later on. The given suffix must match the regular expression.\w[\w-.]+\w

periodinteger · secondsOptionalDeprecated

Use 'token_period' instead.

renewablebooleanOptional

Tokens created via this role will be renewable or not according to this value. Defaults to "true".

Default: true
token_bound_cidrsstring[]Optional

Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.

token_explicit_max_ttlinteger · secondsOptional

If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.

token_no_default_policybooleanOptional

If true, the 'default' policy will not automatically be added to generated tokens

token_num_usesintegerOptional

The maximum number of times a token may be used, a value of zero means unlimited

token_periodinteger · secondsOptional

If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").

token_typestringOptional

The type of token to generate, service or batch

Default: default-service
Responses
200
Token role created or updated successfully
application/json
400
Invalid role configuration
application/json
403
Permission denied
application/json
post
POST /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 175

{
  "allowed_policies": [
    "dev"
  ],
  "orphan": false,
  "renewable": true,
  "allowed_entity_aliases": [
    "web-entity-alias",
    "app-entity-*"
  ],
  "token_bound_cidrs": [
    "127.0.0.1/32",
    "128.252.0.0/16"
  ]
}
{
  "data": null,
  "warnings": null,
  "auth": null
}