oauth2_client.md.tmpl

---
page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
subcategory: ""
description: |-
  Manages an Ory Network OAuth2 client.
---

# {{.Name}} ({{.Type}})

Manages an Ory Network OAuth2 client.

OAuth2 clients are used for machine-to-machine authentication or user-facing OAuth2/OIDC flows.

-> **Plan:** Available on all Ory Network plans.

~> **Important:** The `client_secret` is only returned when the client is first created. Store it securely immediately after creation. It cannot be retrieved later, including after `terraform import`.

## Custom Client ID

By default, a random `client_id` is generated when the client is created. You can specify a custom `client_id` for consistency across environments:

```hcl
resource "ory_oauth2_client" "api" {
  client_id   = "my-api-client"
  client_name = "API Client"
  grant_types = ["client_credentials"]
  scope       = "read write"
}
```

~> **Note:** Changing the `client_id` after creation forces the resource to be destroyed and recreated. The `client_id` must be unique within the project.

## Example Usage

{{ tffile "examples/resources/ory_oauth2_client/resource.tf" }}

## Grant Types

| Grant Type | Description | Use Case |
|------------|-------------|----------|
| `authorization_code` | Authorization Code flow | Web apps, SPAs with PKCE |
| `client_credentials` | Client Credentials flow | Machine-to-machine / API access |
| `refresh_token` | Refresh Token grant | Long-lived sessions (pair with another grant) |
| `implicit` | Implicit flow (legacy) | Legacy SPAs (not recommended) |
| `urn:ietf:params:oauth:grant-type:device_code` | Device Authorization | IoT devices, CLIs |

## Response Types

| Response Type | Description |
|---------------|-------------|
| `code` | Authorization code (used with `authorization_code` grant) |
| `token` | Access token (used with `implicit` grant) |
| `id_token` | ID token (OpenID Connect) |

## Token Endpoint Auth Methods

| Method | Description |
|--------|-------------|
| `client_secret_post` | Secret sent in POST body (default) |
| `client_secret_basic` | Secret sent via HTTP Basic auth header |
| `private_key_jwt` | Client authenticates with a signed JWT |
| `none` | Public client (no secret, used for SPAs) |

## Access Token Strategy

The `access_token_strategy` attribute controls the format of issued access tokens:

| Strategy | Description |
|----------|-------------|
| `opaque` | Short, random string tokens (default) |
| `jwt` | Self-contained JSON Web Tokens |

## Consent Behavior

| Attribute | Description |
|-----------|-------------|
| `skip_consent` | When `true`, the user is never asked to grant consent for this client. Useful for first-party clients. |
| `skip_logout_consent` | When `true`, the user is not asked to confirm logout for this client. |

## Subject Type

The `subject_type` attribute controls how the `sub` claim is generated in ID tokens:

| Type | Description |
|------|-------------|
| `public` | Same `sub` value across all clients (default) |
| `pairwise` | Unique `sub` value per client (privacy-preserving) |

## Per-Grant Token Lifespans

Override default token lifespans on a per-client, per-grant basis using Go duration strings (e.g., `1h`, `30m`, `720h`):

| Grant Type | Access Token | ID Token | Refresh Token |
|------------|-------------|----------|---------------|
| Authorization Code | `authorization_code_grant_access_token_lifespan` | `authorization_code_grant_id_token_lifespan` | `authorization_code_grant_refresh_token_lifespan` |
| Client Credentials | `client_credentials_grant_access_token_lifespan` | — | — |
| Device Authorization | `device_authorization_grant_access_token_lifespan` | `device_authorization_grant_id_token_lifespan` | `device_authorization_grant_refresh_token_lifespan` |
| Implicit | `implicit_grant_access_token_lifespan` | `implicit_grant_id_token_lifespan` | — |
| JWT Bearer | `jwt_bearer_grant_access_token_lifespan` | — | — |
| Refresh Token | `refresh_token_grant_access_token_lifespan` | `refresh_token_grant_id_token_lifespan` | `refresh_token_grant_refresh_token_lifespan` |

If not set, the project-level defaults apply.

## OIDC Configuration

| Attribute | Description |
|-----------|-------------|
| `jwks` | Inline JSON Web Key Set as a JSON string. Provide keys directly for `private_key_jwt` authentication. Mutually exclusive with `jwks_uri`. |
| `jwks_uri` | URL of the client's JSON Web Key Set, used with `private_key_jwt` authentication. Mutually exclusive with `jwks`. |
| `userinfo_signed_response_alg` | JWS algorithm for signing UserInfo responses (e.g., `RS256`) |
| `request_object_signing_alg` | JWS algorithm for signing request objects (e.g., `RS256`) |

### Inline JWKS

Use the `jwks` attribute to provide keys directly instead of hosting them at a URL:

```hcl
resource "ory_oauth2_client" "with_jwks" {
  client_name                = "Client with Inline JWKS"
  grant_types                = ["client_credentials"]
  token_endpoint_auth_method = "private_key_jwt"
  scope                      = "api:read"

  jwks = jsonencode({
    keys = [
      {
        kid = "my-key-1"
        kty = "RSA"
        alg = "RS256"
        use = "sig"
        e   = "AQAB"
        n   = "your-rsa-modulus-base64url-encoded"
      }
    ]
  })
}
```

## OIDC Logout

The provider supports both OIDC front-channel and back-channel logout:

- `frontchannel_logout_uri` — The client's URL that the OP will redirect the user-agent to after logout. The OP sends the logout request via the user's browser.
- `backchannel_logout_uri` — The client's URL that the OP will call directly (server-to-server) to notify the client about a logout event.
- `frontchannel_logout_session_required` — Whether the client requires a session identifier (`sid`) in front-channel logout notifications.
- `backchannel_logout_session_required` — Whether the client requires a session identifier (`sid`) in back-channel logout notifications.

## Resource-Level Credentials (Same-Apply with Project Creation)

When creating an `ory_oauth2_client` in the same `terraform apply` as the `ory_project` it belongs to, the provider may not have project credentials at configuration time. Use the `project_slug` and `project_api_key` attributes to pass credentials directly to the resource:

```hcl
resource "ory_project" "main" {
  name        = "my-project"
  environment = "prod"
}

resource "ory_project_api_key" "main" {
  project_id = ory_project.main.id
  name       = "terraform-key"
}

resource "ory_oauth2_client" "api" {
  project_slug    = ory_project.main.slug
  project_api_key = ory_project_api_key.main.value

  client_name   = "API Client"
  grant_types   = ["client_credentials"]
  scope         = "read write"
}
```

These attributes override the provider-level `project_slug` and `project_api_key`. If the provider already has valid project credentials, you do not need to set them on the resource.

## Import

OAuth2 clients can be imported using their client ID:

```shell
terraform import ory_oauth2_client.api <client-id>
```

~> **Note:** When importing, the `client_secret` will **not** be available. The secret is only returned at creation time and cannot be retrieved from the API afterward.

{{ .SchemaMarkdown | trimspace }}