CIMD for Clients

Learn how to create and host Client ID Metadata Documents for your OAuth applications.

With CIMD, your client_id is simply an HTTPS URL that serves your client metadata as JSON. No preregistration necessary — just host your metadata and start using OAuth.

How It Works

Create Metadata

Write a JSON document with your client information

Host at URL

Serve it over HTTPS with proper Content-Type

Use URL as client_id

Pass the metadata URL directly as your client identifier

Hosting Requirements

Critical Requirements

HTTPS only - HTTP URLs are not allowed

Content-Type: application/json - Proper HTTP header required

Stable origin - Use a reliable, long-term domain

Current metadata - Keep information accurate and up-to-date

Metadata Fields

Required Fields

client_id

Must match the URL serving this document

redirect_uris

Array of exact redirect URIs for your application

Recommended Fields

client_name

Human-readable name for your application

logo_uri

URL to your application's logo image

client_uri

URL to your application's homepage

Optional Fields

tos_uri

policy_uri

grant_types

Supported grant types

response_types

Supported response types

post_logout_redirect_uris

Post-logout redirects

Minimal Example

Basic CIMD Document

{
  "client_id": "https://client.dev/oauth/metadata.json",
  "client_name": "client.dev",
  "client_uri": "https://client.dev",
  "redirect_uris": ["https://client.dev/oauth/callback"]
}

This minimal document includes just the essential fields. Host this JSON at the URL specified in client_id.

Real-world Example

Bluesky/ATProto Ecosystem

View Live Example

The Bluesky/ATProto ecosystem uses CIMD-style client metadata. Here's an example from their OAuth implementation:

{
  "client_id": "https://oauthbluesky.onrender.com/oauth/client-metadata.json",
  "client_name": "OAuth Bluesky Demo",
  "client_uri": "https://oauthbluesky.onrender.com",
  "logo_uri": "https://oauthbluesky.onrender.com/logo.png",
  "redirect_uris": [
    "https://oauthbluesky.onrender.com/oauth/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://oauthbluesky.onrender.com/.well-known/jwks.json"
}

Authoring Checklist

Pre-deployment Checklist

URL accessibility

Verify the URL used as client_id returns valid JSON

Exact redirect URIs

Ensure all redirect URIs are exact matches (no wildcards). HTTPS is recommended but not required.

HTTPS and Content-Type

Confirm HTTPS hosting with application/json header

Optional fields for UX

Add logo_uri, client_uri, and policy links for better user experience

JSON validity

Validate JSON syntax and structure

Production vs development

Avoid localhost redirect URIs in production. Use separate CIMD documents for development environments.

Next Steps

CIMD for Servers

Learn how authorization servers can support CIMD clients.

Back to Overview

Return to the main CIMD explainer page.