Skip to main content

Pomerium Zero API Reference (0.1.0)

Download OpenAPI specification:Download

Authentication

The Pomerium Zero API requires authenticated access for both personal accounts and organizations. To send a valid, authenticated request to the Pomerium Zero API:

  1. Generate an API User Token in the Zero Console
  2. Exchange the API User Token for an ID Token at the /token endpoint
  3. Pass the ID token in an Authorization: Bearer {TOKEN} header to authenticate your request

user

The user service enables you to manage users and user information within an organization or namespace.

This service also enables you to create API access user accounts and renew API refresh tokens.

deleteCurrentUser

Delete current user

Authorizations:
bearerAuth

Responses

updateCurrentUserInfo

Fetch and update currently logged in user information from the identity provider

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "email": "user@example.com",
  • "displayName": "string",
  • "needsOnboarding": true,
  • "photoUrl": "string",
  • "type": "user_type_interactive"
}

completeOnboarding

Complete onboarding

Authorizations:
bearerAuth

Responses

listUsersInOrganization

List users

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
userType
string (UserType)
Enum: "user_type_interactive" "user_type_api_access"

Type of user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createApiAccessUser

Create API access user account

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
name
required
string

Freetext user name

role
string (OrganizationRole)
Enum: "owner" "admin" "auditor" "member"

A high level role that describes the level of access a user has to an organization.

  • Owner: Global namespace admin.
  • Admin: Global namespace admin.
  • Auditor: Global namespace viewer.
  • Member: any user who was granted access to the organization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "email": "user@example.com",
  • "displayName": "string",
  • "needsOnboarding": true,
  • "photoUrl": "string",
  • "type": "user_type_interactive",
  • "refreshToken": "string"
}

removeUserFromOrganization

Remove user from organization

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

userId
required
string

ID of user

Responses

RenewApiUserRefreshToken

Renews API user refresh token. The userId must be an API user. Obtaining a new refresh token invalidates any previously issued refresh tokens.

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

userId
required
string

ID of user

Responses

Response samples

Content type
application/json
{
  • "refreshToken": "string"
}

invitation

The invitation service is where you can view and respond to pending invitations to join a professional type organization.

listUserInvitations

List invitations

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

acceptInvitation

Accept invitation

Authorizations:
bearerAuth
path Parameters
invitationId
required
string

ID of invitation

Responses

rejectInvitation

Reject an invitation

Authorizations:
bearerAuth
path Parameters
invitationId
required
string

ID of invitation

Responses

invite

The invite service is where you can manage invitations sent to users to join your organization.

listOrganizationInvites

List invites

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createOrganizationInvite

Create invite

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
emails
required
Array of strings <email> [ items <email > ]
role
required
string (OrganizationRole)
Enum: "owner" "admin" "auditor" "member"

A high level role that describes the level of access a user has to an organization.

  • Owner: Global namespace admin.
  • Admin: Global namespace admin.
  • Auditor: Global namespace viewer.
  • Member: any user who was granted access to the organization

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "role": "owner"
}

Response samples

Content type
application/json
[
  • {
    }
]

deleteOrganizationInvite

Delete invite

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

invitationId
required
string

ID of invitation

Responses

policy

The policy service is where you can manage policies within a namespace in your organization.

You can build a policy by configuring a Pomerium Policy Language (PPL) rule and apply it to a route.

listPolicies

List policies

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
namespaceId
required
string

ID of namespace

includeDescendants
boolean

include resources from descendant namespaces

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createPolicy

Create policy

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
namespaceId
required
string
name
required
string (entityName) [ 1 .. 128 ] characters
enforced
required
boolean
required
PPLRule (object) or Array of PPLRule (objects)
description
required
string
explanation
required
string
remediation
required
string

Responses

Request samples

Content type
application/json
{
  • "namespaceId": "string",
  • "name": "string",
  • "enforced": true,
  • "ppl": {
    },
  • "description": "string",
  • "explanation": "string",
  • "remediation": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "enforced": true,
  • "ppl": {
    },
  • "description": "string",
  • "explanation": "string",
  • "remediation": "string",
  • "routes": [
    ],
  • "enforcedRoutes": [
    ]
}

deletePolicy

Delete policy

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

policyId
required
string

ID of policy

Responses

getPolicy

Get policy

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

policyId
required
string

ID of policy

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "enforced": true,
  • "ppl": {
    },
  • "description": "string",
  • "explanation": "string",
  • "remediation": "string",
  • "routes": [
    ],
  • "enforcedRoutes": [
    ]
}

updatePolicy

Update policy

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

policyId
required
string

ID of policy

Request Body schema: application/json
required
namespaceId
required
string
name
required
string (entityName) [ 1 .. 128 ] characters
enforced
required
boolean
required
PPLRule (object) or Array of PPLRule (objects)
description
required
string
explanation
required
string
remediation
required
string

Responses

Request samples

Content type
application/json
{
  • "namespaceId": "string",
  • "name": "string",
  • "enforced": true,
  • "ppl": {
    },
  • "description": "string",
  • "explanation": "string",
  • "remediation": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "enforced": true,
  • "ppl": {
    },
  • "description": "string",
  • "explanation": "string",
  • "remediation": "string",
  • "routes": [
    ],
  • "enforcedRoutes": [
    ]
}

activityLog

listActivityLogs

List activity logs

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
activityType
string (ActivityType)
Enum: "create" "delete" "update"

Type of activity

entityId
string

ID of entity

entityType
string (EntityType)
Enum: "changeset" "custom_domain" "domain" "key_pair" "namespace" "organization" "policy" "route" "settings" "service_account"

Type of entity

changesetId
string

id of changeset

namespaceId
string

ID of namespace

userId
string

ID of user

offset
integer

offset of the resources

limit
integer

limit number of resources returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

updateSettings

Update settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
logLevel
required
string

Sets the global logging level for Pomerium. Only logs of the desired level and above will be logged.

proxyLogLevel
string

Sets the logging level for the Pomerium Proxy service access logs. Only logs of the desired level and above will be logged.

address
required
string <ipport>

Specifies the IP Address and Port to serve HTTP requests from. If empty, :443 is used.

dnsLookupFamily
required
string (DNSLookupFamily)
Enum: "V4_ONLY" "V6_ONLY" "V4_PREFERRED" "AUTO" "ALL"

Sets the DNS IP address resolution policy.

httpRedirectAddr
string <ipport>

Specifies the IP Address and Port to redirect HTTP to HTTPS traffic on. If unset, no redirect server is started.

timeoutRead
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the amount of time for the entire request stream to be received from the client.

timeoutWrite
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the max stream duration is the maximum time that a stream’s lifetime will span.

timeoutIdle
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams.

cookieName
required
string

Sets the name of the session cookie sent to clients.

cookieSecret
string

Sets the secret used to encrypt and sign session cookies. If you don't provide a cookie secret, Pomerium will generate one for you.

cookieDomain
string

Sets the scope of session cookies issued by Pomerium. If you specify the domain explicitly, then subdomains would also be included.

cookieHttpOnly
required
boolean

If true, this setting forbids JavaScript from accessing the cookie.

cookieExpire
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the lifetime of session cookies. After this interval, users must reauthenticate.

cookieSameSite
string

Sets the SameSite option for cookies, which determines whether or not a cookie is sent with cross-site requests.

certificateAuthorityKeyPairId
string

ID of CA's public and private key pair.

object (StringMap)

Specifies a mapping of HTTP Headers added globally to all managed routes and Pomerium's Authenticate Service.

object (StringMap)

Pass specific user session data to upstream applications as unsigned HTTP request headers.

defaultUpstreamTimeout
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

The default timeout applied to a proxied route when no timeout key is specified by the policy.

metricsAddress
string

Exposes a Prometheus endpoint on the specified port.

tracingProvider
string

The name of the tracing provider (for example, Jaeger or Zipkin).

tracingSampleRate
required
number

Percentage of requests to sample in decimal notation. The default is 0.0001, or .01%.

tracingDatadogAddress
string <hostport>

The host:port address of the Datadog Trace Agent. Defaults to localhost:8126.

tracingJaegerCollectorEndpoint
string

The URL to the Jaeger HTTP Thrift collector.

tracingJaegerAgentEndpoint
string <hostport>

The address of the jaeger-agent where you send Spans to.

tracingZipkinEndpoint
string

The URL to the Zipkin HTTP endpoint.

downstreamMtlsCaKeyPairId
string

Key pair ID of the downstream client CA. If set, requires mTLS for incoming requests.

googleCloudServerlessAuthenticationServiceAccount
string

Specifies the Service Account credentials to support GCP's Authorization Header format.

skipXffAppend
required
boolean

If true, the incoming X-Forwarded-For HTTP header would not be modified.

databrokerStorageConnection
string

The databroker storage connection string.

accessLogFields
Array of strings

Controls which fields are included in the access logs.

authorizeLogFields
Array of strings

Controls which fields are included in the authorize logs.

passIdentityHeaders
required
boolean
autoApplyChangesets
required
boolean
authenticateServiceUrl
string <url>

Specifies the URL to use for the authenticate service, if not using the Hosted Authenticate Service. (This URL should resolve to your Pomerium deployment.)

identityProvider
string (IdentityProviderType)
Enum: "apple" "auth0" "azure" "cognito" "github" "gitlab" "google" "oidc" "okta" "onelogin" "ping"

Identity provider type, if not using the Hosted Authenticate Service.

identityProviderClientId
string

Identity provider client ID, if not using the Hosted Authenticate Service.

identityProviderClientSecret
string

Identity provider client secret, if not using the Hosted Authenticate Service.

object (StringMap)

Identity provider request params, if not using the Hosted Authenticate Service.

identityProviderScopes
Array of strings (StringList)

Identity provider scopes, if not using the Hosted Authenticate Service.

identityProviderUrl
string <url>

Identity provider URL, if not using the Hosted Authenticate Service. (This is required only for certain identity providers types.)

Responses

Request samples

Content type
application/json
{
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

patchSettings

Patch settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
Array
op
required
string
Enum: "add" "remove" "replace" "copy" "move" "test"
path
required
string
value
any
from
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

route

The route service is where you can build and manage routes defined in a namespace within your organization.

listRoutes

List routes

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
namespaceId
required
string

ID of namespace

includeDescendants
boolean

include resources from descendant namespaces

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createRoute

Create route

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
namespaceId
required
string
name
required
string (entityName) [ 1 .. 128 ] characters
from
required
string <url>
to
Array of strings <url> [ items <url > ]
object (RouteDirectResponse)
prefix
string
path
string
regex
string
prefixRewrite
string
regexRewritePattern
string
regexRewriteSubstitution
string
hostRewrite
string
hostRewriteHeader
string
hostPathRegexRewritePattern
string
hostPathRegexRewriteSubstitution
string
regexPriorityOrder
integer <int64>
timeout
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$
idleTimeout
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$
allowWebsockets
required
boolean
allowSpdy
required
boolean
tlsSkipVerify
required
boolean
tlsUpstreamServerName
string
tlsDownstreamServerName
string
tlsCustomCaKeyPairId
string
tlsClientKeyPairId
string
tlsDownstreamClientCaKeyPairId
string
tlsUpstreamAllowRenegotiation
required
boolean
object (StringMap)
object (StringMap)
removeRequestHeaders
Array of strings
Array of objects (RouteRewriteHeader)
preserveHostHeader
required
boolean
passIdentityHeaders
boolean
kubernetesServiceAccountToken
string
object (RouteRedirect)
enableGoogleCloudServerlessAuthentication
required
boolean
jwtIssuerFormat
string (JwtIssuerFormat)
Enum: "hostOnly" "uri"
showErrorDetails
required
boolean
RouteHttpHealthCheck (object) or RouteTcpHealthCheck (object) or RouteGrpcHealthCheck (object) (RouteHealthCheck)
loadBalancingPolicy
string (RouteLoadBalancingPolicy)
Enum: "round_robin" "least_request" "ring_hash" "random" "maglev"
identityProviderClientId
string
identityProviderClientSecret
string
policyIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "namespaceId": "string",
  • "name": "string",
  • "from": "string",
  • "to": [
    ],
  • "response": {
    },
  • "prefix": "string",
  • "path": "string",
  • "regex": "string",
  • "prefixRewrite": "string",
  • "regexRewritePattern": "string",
  • "regexRewriteSubstitution": "string",
  • "hostRewrite": "string",
  • "hostRewriteHeader": "string",
  • "hostPathRegexRewritePattern": "string",
  • "hostPathRegexRewriteSubstitution": "string",
  • "regexPriorityOrder": 0,
  • "timeout": "string",
  • "idleTimeout": "string",
  • "allowWebsockets": true,
  • "allowSpdy": true,
  • "tlsSkipVerify": true,
  • "tlsUpstreamServerName": "string",
  • "tlsDownstreamServerName": "string",
  • "tlsCustomCaKeyPairId": "string",
  • "tlsClientKeyPairId": "string",
  • "tlsDownstreamClientCaKeyPairId": "string",
  • "tlsUpstreamAllowRenegotiation": true,
  • "setRequestHeaders": {
    },
  • "setResponseHeaders": {
    },
  • "removeRequestHeaders": [
    ],
  • "rewriteResponseHeaders": [
    ],
  • "preserveHostHeader": true,
  • "passIdentityHeaders": true,
  • "kubernetesServiceAccountToken": "string",
  • "redirect": {
    },
  • "enableGoogleCloudServerlessAuthentication": true,
  • "jwtIssuerFormat": "hostOnly",
  • "showErrorDetails": true,
  • "healthCheck": {
    },
  • "loadBalancingPolicy": "round_robin",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "policyIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "from": "string",
  • "to": [
    ],
  • "response": {
    },
  • "prefix": "string",
  • "path": "string",
  • "regex": "string",
  • "prefixRewrite": "string",
  • "regexRewritePattern": "string",
  • "regexRewriteSubstitution": "string",
  • "hostRewrite": "string",
  • "hostRewriteHeader": "string",
  • "hostPathRegexRewritePattern": "string",
  • "hostPathRegexRewriteSubstitution": "string",
  • "regexPriorityOrder": 0,
  • "timeout": "string",
  • "idleTimeout": "string",
  • "allowWebsockets": true,
  • "allowSpdy": true,
  • "tlsSkipVerify": true,
  • "tlsUpstreamServerName": "string",
  • "tlsDownstreamServerName": "string",
  • "tlsCustomCaKeyPairId": "string",
  • "tlsClientKeyPairId": "string",
  • "tlsDownstreamClientCaKeyPairId": "string",
  • "tlsUpstreamAllowRenegotiation": true,
  • "setRequestHeaders": {
    },
  • "setResponseHeaders": {
    },
  • "removeRequestHeaders": [
    ],
  • "rewriteResponseHeaders": [
    ],
  • "preserveHostHeader": true,
  • "passIdentityHeaders": true,
  • "kubernetesServiceAccountToken": "string",
  • "redirect": {
    },
  • "enableGoogleCloudServerlessAuthentication": true,
  • "jwtIssuerFormat": "hostOnly",
  • "showErrorDetails": true,
  • "healthCheck": {
    },
  • "loadBalancingPolicy": "round_robin",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "policyIds": [
    ],
  • "enforcedPolicies": [
    ],
  • "enforcedPolicyIds": [
    ],
  • "policies": [
    ]
}

deleteRoute

Delete route

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

routeId
required
string

ID of route

Responses

getRoute

Get route

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

routeId
required
string

ID of route

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "from": "string",
  • "to": [
    ],
  • "response": {
    },
  • "prefix": "string",
  • "path": "string",
  • "regex": "string",
  • "prefixRewrite": "string",
  • "regexRewritePattern": "string",
  • "regexRewriteSubstitution": "string",
  • "hostRewrite": "string",
  • "hostRewriteHeader": "string",
  • "hostPathRegexRewritePattern": "string",
  • "hostPathRegexRewriteSubstitution": "string",
  • "regexPriorityOrder": 0,
  • "timeout": "string",
  • "idleTimeout": "string",
  • "allowWebsockets": true,
  • "allowSpdy": true,
  • "tlsSkipVerify": true,
  • "tlsUpstreamServerName": "string",
  • "tlsDownstreamServerName": "string",
  • "tlsCustomCaKeyPairId": "string",
  • "tlsClientKeyPairId": "string",
  • "tlsDownstreamClientCaKeyPairId": "string",
  • "tlsUpstreamAllowRenegotiation": true,
  • "setRequestHeaders": {
    },
  • "setResponseHeaders": {
    },
  • "removeRequestHeaders": [
    ],
  • "rewriteResponseHeaders": [
    ],
  • "preserveHostHeader": true,
  • "passIdentityHeaders": true,
  • "kubernetesServiceAccountToken": "string",
  • "redirect": {
    },
  • "enableGoogleCloudServerlessAuthentication": true,
  • "jwtIssuerFormat": "hostOnly",
  • "showErrorDetails": true,
  • "healthCheck": {
    },
  • "loadBalancingPolicy": "round_robin",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "policyIds": [
    ],
  • "enforcedPolicies": [
    ],
  • "enforcedPolicyIds": [
    ],
  • "policies": [
    ]
}

updateRoute

Update route

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

routeId
required
string

ID of route

Request Body schema: application/json
required
namespaceId
required
string
name
required
string (entityName) [ 1 .. 128 ] characters
from
required
string <url>
to
Array of strings <url> [ items <url > ]
object (RouteDirectResponse)
prefix
string
path
string
regex
string
prefixRewrite
string
regexRewritePattern
string
regexRewriteSubstitution
string
hostRewrite
string
hostRewriteHeader
string
hostPathRegexRewritePattern
string
hostPathRegexRewriteSubstitution
string
regexPriorityOrder
integer <int64>
timeout
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$
idleTimeout
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$
allowWebsockets
required
boolean
allowSpdy
required
boolean
tlsSkipVerify
required
boolean
tlsUpstreamServerName
string
tlsDownstreamServerName
string
tlsCustomCaKeyPairId
string
tlsClientKeyPairId
string
tlsDownstreamClientCaKeyPairId
string
tlsUpstreamAllowRenegotiation
required
boolean
object (StringMap)
object (StringMap)
removeRequestHeaders
Array of strings
Array of objects (RouteRewriteHeader)
preserveHostHeader
required
boolean
passIdentityHeaders
boolean
kubernetesServiceAccountToken
string
object (RouteRedirect)
enableGoogleCloudServerlessAuthentication
required
boolean
jwtIssuerFormat
string (JwtIssuerFormat)
Enum: "hostOnly" "uri"
showErrorDetails
required
boolean
RouteHttpHealthCheck (object) or RouteTcpHealthCheck (object) or RouteGrpcHealthCheck (object) (RouteHealthCheck)
loadBalancingPolicy
string (RouteLoadBalancingPolicy)
Enum: "round_robin" "least_request" "ring_hash" "random" "maglev"
identityProviderClientId
string
identityProviderClientSecret
string
policyIds
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "namespaceId": "string",
  • "name": "string",
  • "from": "string",
  • "to": [
    ],
  • "response": {
    },
  • "prefix": "string",
  • "path": "string",
  • "regex": "string",
  • "prefixRewrite": "string",
  • "regexRewritePattern": "string",
  • "regexRewriteSubstitution": "string",
  • "hostRewrite": "string",
  • "hostRewriteHeader": "string",
  • "hostPathRegexRewritePattern": "string",
  • "hostPathRegexRewriteSubstitution": "string",
  • "regexPriorityOrder": 0,
  • "timeout": "string",
  • "idleTimeout": "string",
  • "allowWebsockets": true,
  • "allowSpdy": true,
  • "tlsSkipVerify": true,
  • "tlsUpstreamServerName": "string",
  • "tlsDownstreamServerName": "string",
  • "tlsCustomCaKeyPairId": "string",
  • "tlsClientKeyPairId": "string",
  • "tlsDownstreamClientCaKeyPairId": "string",
  • "tlsUpstreamAllowRenegotiation": true,
  • "setRequestHeaders": {
    },
  • "setResponseHeaders": {
    },
  • "removeRequestHeaders": [
    ],
  • "rewriteResponseHeaders": [
    ],
  • "preserveHostHeader": true,
  • "passIdentityHeaders": true,
  • "kubernetesServiceAccountToken": "string",
  • "redirect": {
    },
  • "enableGoogleCloudServerlessAuthentication": true,
  • "jwtIssuerFormat": "hostOnly",
  • "showErrorDetails": true,
  • "healthCheck": {
    },
  • "loadBalancingPolicy": "round_robin",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "policyIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "name": "string",
  • "from": "string",
  • "to": [
    ],
  • "response": {
    },
  • "prefix": "string",
  • "path": "string",
  • "regex": "string",
  • "prefixRewrite": "string",
  • "regexRewritePattern": "string",
  • "regexRewriteSubstitution": "string",
  • "hostRewrite": "string",
  • "hostRewriteHeader": "string",
  • "hostPathRegexRewritePattern": "string",
  • "hostPathRegexRewriteSubstitution": "string",
  • "regexPriorityOrder": 0,
  • "timeout": "string",
  • "idleTimeout": "string",
  • "allowWebsockets": true,
  • "allowSpdy": true,
  • "tlsSkipVerify": true,
  • "tlsUpstreamServerName": "string",
  • "tlsDownstreamServerName": "string",
  • "tlsCustomCaKeyPairId": "string",
  • "tlsClientKeyPairId": "string",
  • "tlsDownstreamClientCaKeyPairId": "string",
  • "tlsUpstreamAllowRenegotiation": true,
  • "setRequestHeaders": {
    },
  • "setResponseHeaders": {
    },
  • "removeRequestHeaders": [
    ],
  • "rewriteResponseHeaders": [
    ],
  • "preserveHostHeader": true,
  • "passIdentityHeaders": true,
  • "kubernetesServiceAccountToken": "string",
  • "redirect": {
    },
  • "enableGoogleCloudServerlessAuthentication": true,
  • "jwtIssuerFormat": "hostOnly",
  • "showErrorDetails": true,
  • "healthCheck": {
    },
  • "loadBalancingPolicy": "round_robin",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "policyIds": [
    ],
  • "enforcedPolicies": [
    ],
  • "enforcedPolicyIds": [
    ],
  • "policies": [
    ]
}

getRouteCertificates

Get certificates that match the given route

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

routeId
required
string

ID of route

Responses

Response samples

Content type
application/json
[
  • {
    }
]

token

The token service is where you can exchange a valid API refresh token for a new ID token.

getIdToken

Exchange API refresh token for ID token

Request Body schema: application/json
required
refreshToken
required
string

API refresh token

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "idToken": "string",
  • "expiresInSeconds": "string"
}

keyPair

The keypair service is where you can manage global- and route-level certificates for your organization.

listKeyPairs

List key pairs

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
namespaceId
required
string

ID of namespace

includeDescendants
boolean

include resources from descendant namespaces

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createKeyPair

Create keyPair

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
key
string
namespaceId
required
string
certificate
string
name
string

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "namespaceId": "string",
  • "certificate": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "certificateInfo": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "certificate": "string",
  • "name": "string",
  • "hasKey": true,
  • "origin": "system",
  • "status": "pending"
}

deleteKeyPair

Delete keyPair

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

keyPairId
required
string

ID of namespace

Responses

getKeyPair

Get keyPair

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

keyPairId
required
string

ID of namespace

Responses

Response samples

Content type
application/json
{
  • "certificateInfo": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "certificate": "string",
  • "name": "string",
  • "hasKey": true,
  • "origin": "system",
  • "status": "pending"
}

updateKeyPair

Update keyPair. If the certificate and/or key is not set the existing certificate and/or key will be preserved.

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

keyPairId
required
string

ID of namespace

Request Body schema: application/json
required
key
string
namespaceId
required
string
certificate
string
name
string

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "namespaceId": "string",
  • "certificate": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "certificateInfo": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "namespaceId": "string",
  • "certificate": "string",
  • "name": "string",
  • "hasKey": true,
  • "origin": "system",
  • "status": "pending"
}

namespace

The namespace service is where you can manage namespaces within an organization.

listNamespaces

List namespaces

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

changeset

The changeset service is where you can list, get, and apply changesets within a cluster or namespace.

listChangesets

List changesets

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
clusterId
string

ID of cluster

status
string (ChangesetStatus)
Enum: "pending" "applying" "applied" "failed" "current" "rejected"

status of changeset

offset
integer

offset of the resources

limit
integer

limit number of resources returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

compareChangesets

Compare changesets

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

query Parameters
clusterId
required
string

ID of cluster

firstId
string

id of the first changeset to compare

secondId
string

id of the second changeset to compare

Responses

Response samples

Content type
application/json
{
  • "startChangeset": {
    },
  • "endChangeset": {
    },
  • "entities": [
    ]
}

applyChangeset

Apply changeset

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

changesetId
required
string

ID of changeset

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "failureMessage": "string",
  • "namespaceId": "string",
  • "status": "pending"
}

updateSettings

Update settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
logLevel
required
string

Sets the global logging level for Pomerium. Only logs of the desired level and above will be logged.

proxyLogLevel
string

Sets the logging level for the Pomerium Proxy service access logs. Only logs of the desired level and above will be logged.

address
required
string <ipport>

Specifies the IP Address and Port to serve HTTP requests from. If empty, :443 is used.

dnsLookupFamily
required
string (DNSLookupFamily)
Enum: "V4_ONLY" "V6_ONLY" "V4_PREFERRED" "AUTO" "ALL"

Sets the DNS IP address resolution policy.

httpRedirectAddr
string <ipport>

Specifies the IP Address and Port to redirect HTTP to HTTPS traffic on. If unset, no redirect server is started.

timeoutRead
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the amount of time for the entire request stream to be received from the client.

timeoutWrite
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the max stream duration is the maximum time that a stream’s lifetime will span.

timeoutIdle
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams.

cookieName
required
string

Sets the name of the session cookie sent to clients.

cookieSecret
string

Sets the secret used to encrypt and sign session cookies. If you don't provide a cookie secret, Pomerium will generate one for you.

cookieDomain
string

Sets the scope of session cookies issued by Pomerium. If you specify the domain explicitly, then subdomains would also be included.

cookieHttpOnly
required
boolean

If true, this setting forbids JavaScript from accessing the cookie.

cookieExpire
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the lifetime of session cookies. After this interval, users must reauthenticate.

cookieSameSite
string

Sets the SameSite option for cookies, which determines whether or not a cookie is sent with cross-site requests.

certificateAuthorityKeyPairId
string

ID of CA's public and private key pair.

object (StringMap)

Specifies a mapping of HTTP Headers added globally to all managed routes and Pomerium's Authenticate Service.

object (StringMap)

Pass specific user session data to upstream applications as unsigned HTTP request headers.

defaultUpstreamTimeout
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

The default timeout applied to a proxied route when no timeout key is specified by the policy.

metricsAddress
string

Exposes a Prometheus endpoint on the specified port.

tracingProvider
string

The name of the tracing provider (for example, Jaeger or Zipkin).

tracingSampleRate
required
number

Percentage of requests to sample in decimal notation. The default is 0.0001, or .01%.

tracingDatadogAddress
string <hostport>

The host:port address of the Datadog Trace Agent. Defaults to localhost:8126.

tracingJaegerCollectorEndpoint
string

The URL to the Jaeger HTTP Thrift collector.

tracingJaegerAgentEndpoint
string <hostport>

The address of the jaeger-agent where you send Spans to.

tracingZipkinEndpoint
string

The URL to the Zipkin HTTP endpoint.

downstreamMtlsCaKeyPairId
string

Key pair ID of the downstream client CA. If set, requires mTLS for incoming requests.

googleCloudServerlessAuthenticationServiceAccount
string

Specifies the Service Account credentials to support GCP's Authorization Header format.

skipXffAppend
required
boolean

If true, the incoming X-Forwarded-For HTTP header would not be modified.

databrokerStorageConnection
string

The databroker storage connection string.

accessLogFields
Array of strings

Controls which fields are included in the access logs.

authorizeLogFields
Array of strings

Controls which fields are included in the authorize logs.

passIdentityHeaders
required
boolean
autoApplyChangesets
required
boolean
authenticateServiceUrl
string <url>

Specifies the URL to use for the authenticate service, if not using the Hosted Authenticate Service. (This URL should resolve to your Pomerium deployment.)

identityProvider
string (IdentityProviderType)
Enum: "apple" "auth0" "azure" "cognito" "github" "gitlab" "google" "oidc" "okta" "onelogin" "ping"

Identity provider type, if not using the Hosted Authenticate Service.

identityProviderClientId
string

Identity provider client ID, if not using the Hosted Authenticate Service.

identityProviderClientSecret
string

Identity provider client secret, if not using the Hosted Authenticate Service.

object (StringMap)

Identity provider request params, if not using the Hosted Authenticate Service.

identityProviderScopes
Array of strings (StringList)

Identity provider scopes, if not using the Hosted Authenticate Service.

identityProviderUrl
string <url>

Identity provider URL, if not using the Hosted Authenticate Service. (This is required only for certain identity providers types.)

Responses

Request samples

Content type
application/json
{
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

patchSettings

Patch settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
Array
op
required
string
Enum: "add" "remove" "replace" "copy" "move" "test"
path
required
string
value
any
from
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

settings

Manage configuration settings for a cluster within an organization.

getSettings

Get settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

updateSettings

Update settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
logLevel
required
string

Sets the global logging level for Pomerium. Only logs of the desired level and above will be logged.

proxyLogLevel
string

Sets the logging level for the Pomerium Proxy service access logs. Only logs of the desired level and above will be logged.

address
required
string <ipport>

Specifies the IP Address and Port to serve HTTP requests from. If empty, :443 is used.

dnsLookupFamily
required
string (DNSLookupFamily)
Enum: "V4_ONLY" "V6_ONLY" "V4_PREFERRED" "AUTO" "ALL"

Sets the DNS IP address resolution policy.

httpRedirectAddr
string <ipport>

Specifies the IP Address and Port to redirect HTTP to HTTPS traffic on. If unset, no redirect server is started.

timeoutRead
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the amount of time for the entire request stream to be received from the client.

timeoutWrite
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the max stream duration is the maximum time that a stream’s lifetime will span.

timeoutIdle
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams.

cookieName
required
string

Sets the name of the session cookie sent to clients.

cookieSecret
string

Sets the secret used to encrypt and sign session cookies. If you don't provide a cookie secret, Pomerium will generate one for you.

cookieDomain
string

Sets the scope of session cookies issued by Pomerium. If you specify the domain explicitly, then subdomains would also be included.

cookieHttpOnly
required
boolean

If true, this setting forbids JavaScript from accessing the cookie.

cookieExpire
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

Sets the lifetime of session cookies. After this interval, users must reauthenticate.

cookieSameSite
string

Sets the SameSite option for cookies, which determines whether or not a cookie is sent with cross-site requests.

certificateAuthorityKeyPairId
string

ID of CA's public and private key pair.

object (StringMap)

Specifies a mapping of HTTP Headers added globally to all managed routes and Pomerium's Authenticate Service.

object (StringMap)

Pass specific user session data to upstream applications as unsigned HTTP request headers.

defaultUpstreamTimeout
required
string (Duration) ^([0-9]+(y|w|d|h|m|s|ms))+$

The default timeout applied to a proxied route when no timeout key is specified by the policy.

metricsAddress
string

Exposes a Prometheus endpoint on the specified port.

tracingProvider
string

The name of the tracing provider (for example, Jaeger or Zipkin).

tracingSampleRate
required
number

Percentage of requests to sample in decimal notation. The default is 0.0001, or .01%.

tracingDatadogAddress
string <hostport>

The host:port address of the Datadog Trace Agent. Defaults to localhost:8126.

tracingJaegerCollectorEndpoint
string

The URL to the Jaeger HTTP Thrift collector.

tracingJaegerAgentEndpoint
string <hostport>

The address of the jaeger-agent where you send Spans to.

tracingZipkinEndpoint
string

The URL to the Zipkin HTTP endpoint.

downstreamMtlsCaKeyPairId
string

Key pair ID of the downstream client CA. If set, requires mTLS for incoming requests.

googleCloudServerlessAuthenticationServiceAccount
string

Specifies the Service Account credentials to support GCP's Authorization Header format.

skipXffAppend
required
boolean

If true, the incoming X-Forwarded-For HTTP header would not be modified.

databrokerStorageConnection
string

The databroker storage connection string.

accessLogFields
Array of strings

Controls which fields are included in the access logs.

authorizeLogFields
Array of strings

Controls which fields are included in the authorize logs.

passIdentityHeaders
required
boolean
autoApplyChangesets
required
boolean
authenticateServiceUrl
string <url>

Specifies the URL to use for the authenticate service, if not using the Hosted Authenticate Service. (This URL should resolve to your Pomerium deployment.)

identityProvider
string (IdentityProviderType)
Enum: "apple" "auth0" "azure" "cognito" "github" "gitlab" "google" "oidc" "okta" "onelogin" "ping"

Identity provider type, if not using the Hosted Authenticate Service.

identityProviderClientId
string

Identity provider client ID, if not using the Hosted Authenticate Service.

identityProviderClientSecret
string

Identity provider client secret, if not using the Hosted Authenticate Service.

object (StringMap)

Identity provider request params, if not using the Hosted Authenticate Service.

identityProviderScopes
Array of strings (StringList)

Identity provider scopes, if not using the Hosted Authenticate Service.

identityProviderUrl
string <url>

Identity provider URL, if not using the Hosted Authenticate Service. (This is required only for certain identity providers types.)

Responses

Request samples

Content type
application/json
{
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

patchSettings

Patch settings

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
Array
op
required
string
Enum: "add" "remove" "replace" "copy" "move" "test"
path
required
string
value
any
from
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "logLevel": "string",
  • "proxyLogLevel": "string",
  • "address": "string",
  • "dnsLookupFamily": "V4_ONLY",
  • "httpRedirectAddr": "string",
  • "timeoutRead": "string",
  • "timeoutWrite": "string",
  • "timeoutIdle": "string",
  • "cookieName": "string",
  • "cookieSecret": "string",
  • "cookieDomain": "string",
  • "cookieHttpOnly": true,
  • "cookieExpire": "string",
  • "cookieSameSite": "string",
  • "certificateAuthorityKeyPairId": "string",
  • "setResponseHeaders": {
    },
  • "jwtClaimsHeaders": {
    },
  • "defaultUpstreamTimeout": "string",
  • "metricsAddress": "string",
  • "tracingProvider": "string",
  • "tracingSampleRate": 0,
  • "tracingDatadogAddress": "string",
  • "tracingJaegerCollectorEndpoint": "string",
  • "tracingJaegerAgentEndpoint": "string",
  • "tracingZipkinEndpoint": "string",
  • "downstreamMtlsCaKeyPairId": "string",
  • "googleCloudServerlessAuthenticationServiceAccount": "string",
  • "skipXffAppend": true,
  • "databrokerStorageConnection": "string",
  • "accessLogFields": [
    ],
  • "authorizeLogFields": [
    ],
  • "passIdentityHeaders": true,
  • "autoApplyChangesets": true,
  • "authenticateServiceUrl": "string",
  • "identityProvider": "apple",
  • "identityProviderClientId": "string",
  • "identityProviderClientSecret": "string",
  • "identityProviderRequestParams": {
    },
  • "identityProviderScopes": [
    ],
  • "identityProviderUrl": "string"
}

cluster

A cluster represents an isolated Pomerium Core instance within your organization. An organization can have multiple clusters with separate configurations depending on the organization’s use case.

createOrganization

Create organization

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
logoURL
string <url>

URL to an image that will be used as the organization logo. User may provide a URL to an image hosted on a third party service, or upload an image to the dashboard, which would result in an URL being generated.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "logoURL": "string"
}

Response samples

Content type
application/json
{
  • "cluster": {
    },
  • "namespace": {
    },
  • "organization": {
    }
}

listClusters

List clusters

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

createCluster

Create cluster

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

Request Body schema: application/json
required
name
required
string
manualOverrideIpAddress
string <ip> (IPAddress)
domain
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "manualOverrideIpAddress": "string",
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "manualOverrideIpAddress": "string",
  • "fqdn": "string",
  • "autoDetectIpAddress": "string",
  • "namespaceId": "string",
  • "hasFailingHealthChecks": true,
  • "minReplicaVersion": "string",
  • "domain": "string",
  • "onboardingStatus": "string",
  • "importStatus": {
    },
  • "refreshToken": "string"
}

deleteCluster

Delete cluster

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Responses

getCluster

Get cluster

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "manualOverrideIpAddress": "string",
  • "fqdn": "string",
  • "autoDetectIpAddress": "string",
  • "namespaceId": "string",
  • "hasFailingHealthChecks": true,
  • "minReplicaVersion": "string",
  • "domain": "string",
  • "onboardingStatus": "string",
  • "importStatus": {
    }
}

updateCluster

Update cluster

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Request Body schema: application/json
required
name
required
string
manualOverrideIpAddress
string <ip> (IPAddress)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "manualOverrideIpAddress": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "manualOverrideIpAddress": "string",
  • "fqdn": "string",
  • "autoDetectIpAddress": "string",
  • "namespaceId": "string",
  • "hasFailingHealthChecks": true,
  • "minReplicaVersion": "string",
  • "domain": "string",
  • "onboardingStatus": "string",
  • "importStatus": {
    }
}

listClusterReplicas

List replicas known for a cluster

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

query Parameters
startTime
required
string <date-time>

Start time of the time range

endTime
required
string <date-time>

Start time of the time range

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getClusterHealth

Get cluster health check data

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Responses

Response samples

Content type
application/json
[
  • {
    }
]

rotateClusterToken

Rotate cluster identity token. This token is used to authenticate the cluster to the Pomerium Zero API. Only one token may be active at a time. Requesting a new token will invalidate the previous one.

Authorizations:
bearerAuth
path Parameters
organizationId
required
string

ID of organization

clusterId
required
string

ID of cluster

Responses

Response samples

Content type
application/json
{
  • "refreshToken": "string"
}

generateSubdomainName

Generate a subdomain name

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "string"
}

checkIdentityProviderSettings

Check identity provider settings

Authorizations:
bearerAuth
Request Body schema: application/json
required
provider
required
string (IdentityProviderType)
Enum: "apple" "auth0" "azure" "cognito" "github" "gitlab" "google" "oidc" "okta" "onelogin" "ping"
url
string
clientId
string
clientSecret
string
object (StringMap)
scopes
Array of strings (StringList)

Responses

Request samples

Content type
application/json
{
  • "provider": "apple",
  • "url": "string",
  • "clientId": "string",
  • "clientSecret": "string",
  • "requestParams": {
    },
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "errors": {
    }
}

startOnboarding

Start onboarding

Authorizations:
bearerAuth
Request Body schema: application/json
required
system
required
string
timezone
required
string

Responses

Request samples

Content type
application/json
{
  • "system": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "organizationId": "string",
  • "clusterId": "string",
  • "clusterToken": "string"
}

configureOnboarding

Configure onboarding

Authorizations:
bearerAuth
Request Body schema: application/json