Manage OAuth 2.0 and OpenID Connect clients

OAuth2 clients are applications that securely authenticate with the authorization server to obtain access to an HTTP service. Confidential clients can use registered client secrets to authenticate, while public clients are unable to use registered client secrets. OAuth2 clients can be configured in a secure manner using the Ory OAuth2 and OpenID Connect product. This documentation article explains how to manage OAuth2 clients using the Ory Console, Ory SDK, Ory CLI, and Ory REST APIs.

Create OAuth2 client

To create a new OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

The Ory Console is a web-based user interface that allows you to manage OAuth2 clients. To create a new client:

Go to OAuth 2 → Clients and applications in the Ory Console
Click Create OAuth2 Client and complete the form or update an existing client.
When creating a confidential client, copy the client secret when printed. It is only shown once.

ory create oauth2-client \
  --grant-type authorization_code --grant-type refresh_token  --grant-type client_credentials \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback --redirect-uri http://my-other-app.com/callback

import { Configuration, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOAuth2Client() {
  await ory.createOAuth2Client({
    oAuth2Client: {
      grant_types: ["authorization_code", "refresh_token"],
      redirect_uris: ["https://example.com"],
      scope: "offline openid",
      token_endpoint_auth_method: "client_secret_post",
    },
  })
}

Update OAuth2 client

To update an existing OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

Go to OAuth 2 → Clients and applications in the Ory Console.
Locate the client you want to update.
Click on the pen symbol to update the client's configuration.
When you are finished, scroll to the top and click Save.

ory update oauth2-client --project <project-id> --workspace <workspace-id> {client.id} \
  --grant-type authorization_code --grant-type refresh_token  --grant-type client_credentials \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://a-new-callback

import { Configuration, OAuth2Api, OAuth2Client } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function updateOAuth2Client(
  id: string,
  update: Partial<OAuth2Client>,
) {
  // setOAuth2Client replaces all values (empty ones too),
  // which is why we include the original client.
  const { data: original } = await ory.getOAuth2Client({ id })
  await ory.setOAuth2Client({
    id,
    oAuth2Client: {
      ...original,
      ...update,
    },
  })
}

Patch OAuth2 client

To partially update an existing OAuth2 client, use the following methods:

Ory Console
Ory SDK
REST API

Go to OAuth 2 → Clients and applications in the Ory Console.
Locate the client you want to update.
Click on the pen symbol to update the client's configuration.
When you are finished, scroll to the top and click Save.

import { Configuration, JsonPatch, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function patchOAuth2Client(id: string, patches: JsonPatch[]) {
  await ory.patchOAuth2Client({
    id,
    jsonPatch: [
      ...patches,
      {
        op: "replace",
        path: "owner",
        value: "New owner",
      },
    ],
  })
}

Rotate OAuth2 client secret

OAuth2 client secret rotation allows you to change a client's secret without downtime. When you rotate a secret, the old secret remains valid until you explicitly clean it up, allowing you to update all services using the client credentials without service interruption.

How secret rotation works

Rotate the secret: Generate a new secret for the client
Both secrets work: Old and new secrets both authenticate until cleanup
Update services: Update your applications to use the new secret
Cleanup: Manually remove old rotated secrets once all services are updated

Rotate client secret

To rotate an OAuth2 client secret, use the following methods:

REST API
Ory SDK

curl -X POST https://{project.slug}.projects.oryapis.com/admin/clients/{client-id}/secret/rotate \
  -H "Authorization: Bearer ory_pat_..."

The response includes the new client_secret. Save this value immediately - it will not be shown again.

See API documentation.

import { Configuration, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${projectSlug}.projects.oryapis.com`,
    accessToken: "ory_pat_..."
  })
)

const { data: client } = await ory.rotateOAuth2ClientSecret({
  id: clientId
})

// Save the new client_secret immediately
console.log("New secret:", client.client_secret)

Clear rotated secrets

Once all services have been updated to use the new secret, you can remove the old rotated secrets to revoke access using the old credentials:

REST API
Ory SDK

curl -X DELETE https://{project.slug}.projects.oryapis.com/admin/clients/{client-id}/secret/rotate \
  -H "Authorization: Bearer ory_pat_..."

After cleanup, only the current secret will be valid. Old secrets will no longer authenticate.

See API documentation.

await ory.deleteRotatedOAuth2ClientSecrets({
  id: clientId
})

// Old secrets are now revoked

Secret rotation workflow example

Here's a complete workflow for rotating a client secret:

# 1. Get current client
CLIENT_ID="your-client-id"

# 2. Rotate the secret
NEW_SECRET=$(curl -X POST "https://{project.slug}.projects.oryapis.com/admin/clients/$CLIENT_ID/secret/rotate" \
  -H "Authorization: Bearer ory_pat_..." | jq -r '.client_secret')

echo "New secret: $NEW_SECRET"

# 3. Update your applications with the new secret
# (Both old and new secrets work during this period)

# 4. Verify the new secret works
curl -X POST "https://{project.slug}.projects.oryapis.com/oauth2/token" \
  -u "$CLIENT_ID:$NEW_SECRET" \
  -d "grant_type=client_credentials"

# 5. Once all services are updated, clean up old secrets
curl -X DELETE "https://{project.slug}.projects.oryapis.com/admin/clients/$CLIENT_ID/secret/rotate" \
  -H "Authorization: Bearer ory_pat_..."

# Old secret is now revoked

Zero-downtime credential rotation Secret rotation enables zero-downtime credential updates. Both the old and new secrets

remain valid until you manually clean up the rotated secrets, allowing you to update all your services without service interruption. :::

Security best practice Rotated secrets remain valid indefinitely until you explicitly clean them up. Always remove old

rotated secrets once your migration is complete to ensure that compromised credentials cannot be used. :::

Delete OAuth2 client

To delete an existing OAuth2 client, use the following methods:

Ory Console
Ory CLI
Ory SDK
REST API

Go to OAuth 2 → Clients and applications in the Ory Console.
Locate the client you want to update.
Click on pen symbol to update the client's configuration.
Scroll to the bottom and click Delete Client.

ory delete oauth2-client {client.id}

import { Configuration, OAuth2Api } from "@ory/client"

const ory = new OAuth2Api(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function deleteOAuth2Client(id: string) {
  await ory.deleteOAuth2Client({ id })
}

OpenID Dynamic Client Registration

OpenID Dynamic Client Registration enables automatic registration of OAuth2 clients with the authorization server. When enabled, clients can be created, retrieved, updated, patched, and deleted dynamically without manual configuration. To enable OpenID Dynamic Client Registration, use the Ory CLI:

ory patch oauth2-config --project <project-id> --workspace <workspace-id>
  --replace "/oidc/dynamic_client_registration/enabled=true"

OpenID Connect dynamic registration involves the use of a registration_access_token, which is a bearer token that allows a client to make requests to the OpenID Connect dynamic registration endpoint. The token is issued by the authorization server and can only be used by the client that it was issued to.

It's important to note that the registration_access_token is a sensitive piece of information that should be kept secure. It should only be used by the client that it was issued to and should not be shared with any other parties.

Register OAuth2 and OpenID Connect clients

Use the SDK or REST API to register an OAuth2 and OpenID Connect client:

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOidcDynamicClient() {
  const { data } = await ory.createOidcDynamicClient({
    oAuth2Client: {
      grant_types: ["authorization_code", "refresh_token"],
      redirect_uris: ["https://example.com"],
      scope: "offline openid",
      token_endpoint_auth_method: "client_secret_post",
    },
  })

  console.log(data.registration_access_token) // Write this down, it is only sent once!
  console.log(data.client_id, data.client_secret /* ... */)
}

The response includes the registration_access_token which is needed to manage the client. The token will only be shown once!

Get OAuth2 and OpenID Connect clients

The GET endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to retrieve the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function getOidcDynamicClient(
  id: string,
  registrationAccessToken: string,
) {
  const { data } = await ory.getOidcDynamicClient(
    {
      id,
    },
    {
      headers: {
        Authorization: `Bearer ${registrationAccessToken}`,
      },
    },
  )
}

Update OAuth2 and OpenID Connect clients

The POST endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to update the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OAuth2Client, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function createOidcDynamicClient(
  id: string,
  updatedClient: OAuth2Client,
) {
  const { data } = await ory.setOidcDynamicClient({
    id: id,
    oAuth2Client: {
      ...updatedClient,
      grant_types: ["authorization_code", "refresh_token"],
      // ...
    },
  })

  console.log(data.registration_access_token) // Write this down, it is only sent once!
}

Delete OAuth2 and OpenID Connect clients

The DELETE endpoint requires the client to authenticate with the registration_access_token regardless of the token_endpoint_auth_method. It can be used to delete the OAuth2 and OpenID Connect client.

Ory SDK
REST API

import { Configuration, OidcApi } from "@ory/client"

const ory = new OidcApi(
  new Configuration({
    basePath: `https://${process.env.ORY_PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

export async function deleteOidcDynamicClient(
  id: string,
  registrationAccessToken: string,
) {
  await ory.deleteOidcDynamicClient(
    {
      id,
    },
    {
      headers: {
        Authorization: `Bearer ${registrationAccessToken}`,
      },
    },
  )
}

Example OAuth2 clients

Here are some examples of creating OAuth2 clients with different options:

Client credentials

ory create oauth2-client \
  --grant-type client_credentials \
  --scope my-scope \
  --token-endpoint-auth-method client_secret_basic

Token endpoint auth method

ory create oauth2-client \
  --grant-type authorization_code \
  --response-type code \
  --scope openid \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback

Multiple redirect URIs

ory create oauth2-client \
  --grant-type authorization_code --grant-type refresh_token \
  --response-type code \
  --scope openid --scope offline_access \
  --token-endpoint-auth-method client_secret_post \
  --redirect-uri https://my-app.com/callback --redirect-uri http://my-other-app.com/callback

Create OAuth2 client​

Update OAuth2 client​

Patch OAuth2 client​

Rotate OAuth2 client secret​

How secret rotation works​

Rotate client secret​

Clear rotated secrets​

Secret rotation workflow example​

Delete OAuth2 client​

OpenID Dynamic Client Registration​

Register OAuth2 and OpenID Connect clients​

Get OAuth2 and OpenID Connect clients​

Update OAuth2 and OpenID Connect clients​

Delete OAuth2 and OpenID Connect clients​

Example OAuth2 clients​

Client credentials​

Token endpoint auth method​

Multiple redirect URIs​

Ory Network