Create endpoint OIDC provider

POST

/v1/endpoint-oidc-providers

Default server

Create an OIDC provider that lets users enroll hosts by signing in with their identity provider.

Token scope required: endpoint-oidc-providers:create

Authorizations

ApiToken
endpoint-oidc-providers:create

Request Body^required

object

name

required

string

>= 1 characters <= 50 characters

Example

Corporate SSO

clientID

required

OAuth client ID issued by the identity provider.

string

>= 1 characters <= 255 characters

Example

0oa1b2c3d4e5f6g7h8i9

clientSecret

OAuth client secret issued by the identity provider. Required when creating a provider. Omit when updating to keep the current secret.

string

>= 1 characters <= 255 characters

issuerURL

required

HTTPS issuer URL of the identity provider. Its OpenID Connect discovery document at /.well-known/openid-configuration must be reachable when the request is made, and its issuer field must match this value exactly.

string format: uri

>= 1 characters <= 255 characters

Example

https://example.okta.com

enabled

Whether users can enroll hosts by signing in with this provider. Requires domainID.

boolean

networkID

required

Network that hosts enrolled through this provider join.

string

Example

network-KAOWMXZHZWCVMGGFKM22XEGYLE

roleID

Role assigned to hosts enrolled through this provider.

string | null

Example

role-PZEDBXHCEXKAKJPZ6XOQTIAJA4

authValidityHours

How long, in hours, a host keeps network access after its user signs in. Omit for access that does not expire.

integer | null

>= 1 <= 43800

Example

domainID

Email domain whose users may sign in with this provider. Required when enabled is true, and the domain must be verified before the provider can be enabled. Each domain may be enabled on only one provider.

string | null

Example

domain-3QZRDHZ5SZBQ5DBHUQE6GSMXGI

autoAssignCIDRs

Prefixes from which hosts enrolled through this provider are assigned addresses. Each must exactly match the network’s IPv4 CIDR or IPv6 prefix. On a network with an IPv6 prefix, that prefix is always included even if omitted here. On a network using certificate version 1, the list is replaced with the network’s IPv4 CIDR.

array | null

<= 2 items

Example

[
  "100.100.0.0/22"
]

Example

{
  "name": "Corporate SSO",
  "clientID": "0oa1b2c3d4e5f6g7h8i9",
  "clientSecret": "s3cr3t",
  "issuerURL": "https://example.okta.com",
  "enabled": true,
  "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
  "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
  "authValidityHours": 720,
  "domainID": "domain-3QZRDHZ5SZBQ5DBHUQE6GSMXGI",
  "autoAssignCIDRs": [
    "100.100.0.0/22"
  ]
}

Responses

200

Successful operation

object

data

required

object

required

string

Example

endpointoidc-WDRO5WY4LTKA2AALKZQ2OHBSDE

organizationID

required

string

Example

org-F63A24JGCLJV3ZEUTLCBISGETA

name

required

string

Example

Corporate SSO

clientID

required

string

Example

0oa1b2c3d4e5f6g7h8i9

issuerURL

required

string format: uri

Example

https://example.okta.com

enabled

required

Whether users can enroll hosts by signing in with this provider.

boolean

networkID

required

Network that hosts enrolled through this provider join.

string

Example

network-KAOWMXZHZWCVMGGFKM22XEGYLE

roleID

required

Role assigned to hosts enrolled through this provider.

string | null

Example

role-PZEDBXHCEXKAKJPZ6XOQTIAJA4

authValidityHours

required

How long, in hours, a host keeps network access after its user signs in. null means access does not expire.

integer | null

Example

domainID

required

Email domain whose users may sign in with this provider.

string | null

Example

domain-3QZRDHZ5SZBQ5DBHUQE6GSMXGI

autoAssignCIDRs

required

Prefixes from which hosts enrolled through this provider are assigned addresses. Includes the network’s IPv6 prefix whenever the network has one.

array | null

Example

[
  "100.100.0.0/22",
  "fdef:c0:c0:1::/80"
]

Example

{
  "data": {
    "id": "endpointoidc-WDRO5WY4LTKA2AALKZQ2OHBSDE",
    "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
    "name": "Corporate SSO",
    "clientID": "0oa1b2c3d4e5f6g7h8i9",
    "issuerURL": "https://example.okta.com",
    "enabled": true,
    "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
    "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
    "authValidityHours": 720,
    "domainID": "domain-3QZRDHZ5SZBQ5DBHUQE6GSMXGI",
    "autoAssignCIDRs": [
      "100.100.0.0/22",
      "fdef:c0:c0:1::/80"
    ]
  }
}

400

Validation error

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

A provider already exists with the name.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "name"
    }
  ]
}

The issuer's discovery document at `/.well-known/openid-configuration` could not be fetched or parsed.

{
  "errors": [
    {
      "code": "ERR_OIDC_DISCOVERY_VALIDATION_FAILURE",
      "message": "must have an accessible and valid discovery document",
      "path": "issuerURL"
    }
  ]
}

`issuerURL` does not match the `issuer` field of the discovery document.

{
  "errors": [
    {
      "code": "ERR_OIDC_ISSUER_DISCOVERY_MISMATCH",
      "message": "must match issuer field of discovery document",
      "path": "issuerURL"
    }
  ]
}

`enabled` is `true` but no `domainID` was given.

{
  "errors": [
    {
      "code": "ERR_MISSING_VALUE",
      "message": "domainID must be set if enabled is true",
      "path": "domainID"
    }
  ]
}

The domain is already enabled on another provider.

{
  "errors": [
    {
      "code": "ERR_DOMAIN_ALREADY_ENABLED",
      "message": "domain is already enabled on another provider",
      "path": "domainID"
    }
  ]
}

enabled is true but the domain has not been verified. On update, the message reads "cannot mark an endpoint OIDC provider enabled without a verified domain".

{
  "errors": [
    {
      "code": "ERR_DOMAIN_NOT_VERIFIED",
      "message": "cannot create an enabled endpoint OIDC provider without a verified domain",
      "path": "domainID"
    }
  ]
}

The network, role or domain does not exist.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "networkID"
    }
  ]
}

An `autoAssignCIDRs` entry is an address rather than a CIDR prefix.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "must be a CIDR prefix, not an address",
      "path": "autoAssignCIDRs[0]"
    }
  ]
}

Creating the provider would exceed the organization's limit. Not returned on update.

{
  "errors": [
    {
      "code": "ERR_LIMIT_EXCEEDED",
      "message": "no more than 10 endpoint-oidc-providers are allowed",
      "extra": {
        "limit": 10,
        "limitName": "endpoint-oidc-providers"
      }
    }
  ]
}

401

The API key is missing, invalid or expired.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_UNAUTHORIZED",
      "message": "unauthorized"
    }
  ]
}

403

The API key lacks a required scope.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

The API key lacks a required scope.

{
  "errors": [
    {
      "code": "ERR_FORBIDDEN",
      "message": "api key must support the following scopes: hosts:read"
    }
  ]
}

429

The organization has exceeded its API request rate limit. Retry the request after a short delay.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_TOO_MANY_REQUESTS",
      "message": "too many requests"
    }
  ]
}

Create endpoint OIDC provider

Authorizations

Request Body required

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

400

Examples

401

Example

403

Examples

429

Example

Request Body^required