GatePlane Documentation

HTTP API Reference

4 min read

This page covers the API endpoints exposed by all GatePlane plugins.

The configuration endpoint (/config) contains feature-specific fields, covered separately under each respective Configuration section in GatePlane Features.

Authentication

All endpoints require a valid Vault/OpenBao token with appropriate policies assigned to a Vault/OpenBao Entity.

The /config is an exception, as it can be used by tokens not assigned to a Vault/OpenBao Entities (e.g: root token).

Warning

Endpoints that issue Vault/OpenBao tokens (like the Policy Gate’s /claim endpoint) reject authenticated requests, as explained in this Github Issue hashicorp/vault#6074.

This makes the Policy Gate’s /claim endpoint the only exception of this section, effectively rendering it an unauthenticated endpoint.

API Endpoints

Request Access (POST /request)

Users request access by making a POST request to this endpoint.

Request

curl --header "X-Vault-Token: <user-token>" \
     --request POST \
     --data '{"reason":"Emergency fix required on production (Ticket 123)"}' \
     http://vault/v1/auth/plugin/request

Response

{
  "exp": "2025-05-01T20:13:38.878161835Z",
  "iat": "2025-05-01T19:13:38.878161835Z",
  "message": "request registered",
  "overwrite": true,
  "reason": "Emergency fix required on production (Ticket 123)",
  "request_id": "ecdbcf78-99f1-1c02-ca2e-5d7bf156eaaf",
  "status": "pending"
},

RequestID == Requestor Entity ID

The value of request_id currently collides with the Vault/OpenBao Entity ID of the requestor.

This is considered an internal decision bound to change in future versions of the plugins.

List Access Requests (LIST /request)

Returns a list of current access requests along with metadata including request time, expiration, number of approvers, and whether the caller has approved each request.

Request

curl --header "X-Vault-Token: <token>" \
     --request LIST \
     http://vault/v1/auth/plugin/request

Response

{
  "keys": [
    "ecdbcf78-99f1-1c02-ca2e-5d7bf156eaaf",
  ],
  "key_info": [
    {
      "exp": "2025-05-01T20:13:38.878161835Z",
      "have_approved": false,
      "iat": "2025-05-01T19:13:38.878161835Z",
      "num_approvals": 0,
      "reason": "Emergency fix required on production (Ticket 123)",
      "remaining_approvals": 1,
      "request_id": "ecdbcf78-99f1-1c02-ca2e-5d7bf156eaaf",
      "status": "pending"
    }
  ]
}

Get Access Requests (GET /request)

Returns the data of the access request created by the calling Entity.

The field grant_code is set to "" if the access request is not fully approved. If the access request is approved, the grant_code field contains a UUIDv4.

Hint

This endpoint does not support arbitrary reading of Access Requests of others.

It accepts no parameters and only returns the details of an Access Request if the requestor has made one.

Request

curl --header "X-Vault-Token: <token>" \
     --request GET \
     http://vault/v1/auth/plugin/request

Response

{
  "exp": "2025-05-01T20:13:38.878161835Z",
  "grant_code": "3a9e705b-4f6a-1dee-0caa-c11a1424b8e2",
  "iat": "2025-05-01T19:13:38.878161835Z",
  "reason": "Emergency fix required on production (Ticket 123)",
  "request_id": "ecdbcf78-99f1-1c02-ca2e-5d7bf156eaaf",
  "status": "approved"
}

Warning

The grant_code is a nonce considered a secret, as it is only available to the requestor by this call.

Its sole purpose is to be used to interact with the /claim endpoint.

Approve Access Request (POST /approve)

Users with update access to this endpoint can approve access requests.

Request

curl --header "X-Vault-Token: <token>" \
     --request POST \
     --data '{"request_id": "<request_uuid>"}' \
     http://vault/v1/auth/plugin/approve

Response

{
  "access_approved": true,
  "approval_id": "ecdbcf78-99f1-1c02-ca2e-5d7bf156eaaf:cccb8039-fca9-c2f7-ad4a-9a0e3db1cb59:+",
  "exp": "2025-05-01T20:20:34.404665696Z",
  "iat": "2025-05-01T19:20:34.404665696Z",
  "message": "access approved"
}

Requestors CANNOT approve their own requests!

Approving an Access Request issued by the approver themselves will fail with an HTTP 403 Forbidden status code.

This is a deliberate decision to prevent privilege escalations (requestors approving their own requests)!

Claim Access (POST /claim)

This endpoint consumes a grant_code (retrieved by reading the request endpoint of an approved Access Request) and performs the action defined for each plugin:

Policy Gate

This endpoint issues a Vault/OpenBao token with the Vault/OpenBao policies configured under the mount’s /config endpoint.

Okta Group Gate

This endpoint fetches the requestors Okta ID (e.g: 00up44uglx1peDV6n5d7)frm the Vault/OpenBao Entity name or metadata field (WIP) and adds them temporarily to an Okta Group configured under the mount’s /config endpoint.

This endpoint is authenticated for all plugins except Policy Gate, as authenticated endpoints that serve Vault/OpenBao tokens are limited to the internal /token path, as described here.

Request

curl --header "X-Vault-Token: <token>" \ 	# <-- authenticated in every case except Policy Gate
     --request POST \
     --data '{"grant_code": "<uuid-token>"}' \
     http://vault/v1/auth/plugin/claim

Response

  • Policy Gate
{
  "auth": {
    "client_token": "s.[...]",
    "policies": ["production-admin", "db-admin", "vault-admin"],
    "lease_duration": 1800,
    "metadata": {
        "grantedBy": "gateplane-policy-gate",
    },
  }
}
  • Okta Group Gate
{
  "data": {
    "exp":             "2025-05-01T20:20:34.404665696Z",
    "okta_user_id":    "00up44uglx1peDV6n5d7",
    "okta_group_name": "Cloud Console Admins"
  }
}

Configuration (GET /config)

Users can view the plugin settings

Request

curl --header "X-Vault-Token: <token>" \
    --request GET \
    http://127.0.0.1:8200/v1/auth/plugin/config

Response

{
    "approval_ttl":       3600,
    "request_ttl":        3600,
    "required_approvals": 1,
    "require_reason":     false,
    "delete_after":       84600,
    [...] // other fields depending on the plugin
}

Configuration (POST /config)

Admins configure the plugin settings.

Request

curl --header "X-Vault-Token: <admin-token>" \
    --request POST \
    http://127.0.0.1:8200/v1/auth/plugin/config \
    --data @payload.json

Payload

{
    "approval_ttl":       3600,
    "request_ttl":        3600,
    "required_approvals": 1,
    "require_reason":     false,
    "delete_after":       84600,
    [...] // other fields depending on the plugin
}

Response

This call provides an empty response.

This documentation page follows HashiCorp Vault’s API structure.

Backlinks