openapi: 3.1.0
# generated: '2026-07-18'
# method: generated
# source: https://www.doximity.com/developers/documentation + https://auth.doximity.com/.well-known/openid-configuration
# NOTE: Faithful OpenAPI generated by the API Evangelist enrichment pipeline from Doximity's
# published developer documentation and OpenID Connect discovery metadata. Doximity does not
# publish an OpenAPI itself; every path, parameter, scope, and claim below is transcribed from
# the public docs and the live /.well-known/openid-configuration. Not an official Doximity artifact.
info:
title: Doximity OAuth 2.0 & OpenID Connect API
version: '1.0'
description: >-
OAuth 2.0 authorization server and OpenID Connect provider that authenticates and identifies
verified Doximity medical professionals against the Doximity medical database. Uses the
Authorization Code grant with mandatory PKCE (S256), refresh tokens, and the device_code grant.
contact:
name: Doximity Business Development
email: bd@doximity.com
url: https://www.doximity.com/developers/documentation
termsOfService: https://www.doximity.com/terms-of-service
servers:
- url: https://auth.doximity.com
description: Production authorization server
tags:
- name: OAuth
description: OAuth 2.0 authorization and token endpoints
- name: OpenID Connect
description: Identity and discovery endpoints
paths:
/oauth/authorize:
get:
operationId: authorize
tags: [OAuth]
summary: Start the Authorization Code flow
description: >-
Redirect the user's browser here to begin the Authorization Code grant with PKCE. On approval
Doximity redirects back to redirect_uri with a short-lived authorization code and state.
parameters:
- {name: client_id, in: query, required: true, schema: {type: string}, description: Your application client id}
- {name: response_type, in: query, required: true, schema: {type: string, enum: [code, "code id_token", id_token]}}
- {name: redirect_uri, in: query, required: true, schema: {type: string, format: uri}}
- {name: scope, in: query, required: true, schema: {type: string}, description: Space-delimited scopes; must include openid}
- {name: state, in: query, required: true, schema: {type: string}, description: Opaque CSRF-mitigation value echoed back}
- {name: code_challenge, in: query, required: true, schema: {type: string}, description: PKCE code challenge}
- {name: code_challenge_method, in: query, required: true, schema: {type: string, enum: [S256]}}
- {name: nonce, in: query, required: false, schema: {type: string}}
- {name: prompt, in: query, required: false, schema: {type: string, enum: [none, login, consent, create]}}
- {name: display, in: query, required: false, schema: {type: string, enum: [page, popup]}}
- {name: response_mode, in: query, required: false, schema: {type: string, enum: [query, fragment]}}
- {name: id_token_hint, in: query, required: false, schema: {type: string}}
responses:
'302':
description: Redirect to redirect_uri with code+state on success, or error+error_description on denial.
/oauth/token:
post:
operationId: token
tags: [OAuth]
summary: Exchange an authorization code or refresh token for tokens
description: Token endpoint. Authenticate with HTTP Basic (client_secret_basic).
security:
- clientBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
grant_type:
type: string
enum: [authorization_code, refresh_token, "urn:ietf:params:oauth:grant-type:device_code"]
code: {type: string}
redirect_uri: {type: string, format: uri}
code_verifier: {type: string, description: PKCE verifier}
refresh_token: {type: string}
scope: {type: string}
required: [grant_type]
responses:
'200':
description: Token response
content:
application/json:
schema: {$ref: '#/components/schemas/TokenResponse'}
'400':
description: Invalid request / invalid_grant
content:
application/json:
schema: {$ref: '#/components/schemas/OAuthError'}
'401':
description: Invalid client credentials
content:
application/json:
schema: {$ref: '#/components/schemas/OAuthError'}
'429':
description: Rate limit exceeded
/oauth/userinfo:
get:
operationId: userinfo
tags: [OpenID Connect]
summary: Fetch the authenticated member's identity claims
description: Returns the OpenID Connect claims permitted by the granted scopes. Requires a bearer access token.
security:
- bearerAuth: []
responses:
'200':
description: UserInfo claims (JWT signed RS256 or JSON)
content:
application/json:
schema: {$ref: '#/components/schemas/UserInfo'}
'401':
description: Missing or invalid access token
'403':
description: Insufficient scope
'429':
description: Rate limit exceeded
/oauth/revoke:
post:
operationId: revoke
tags: [OAuth]
summary: Revoke an access or refresh token
security:
- clientBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token: {type: string}
required: [token]
responses:
'200': {description: Token revoked}
/oauth/logout:
get:
operationId: logout
tags: [OpenID Connect]
summary: End the Doximity session (RP-initiated logout)
parameters:
- {name: id_token_hint, in: query, required: false, schema: {type: string}}
- {name: post_logout_redirect_uri, in: query, required: false, schema: {type: string, format: uri}}
- {name: state, in: query, required: false, schema: {type: string}}
responses:
'302': {description: Redirect to post_logout_redirect_uri}
/oauth/session_state:
post:
operationId: sessionState
tags: [OpenID Connect]
summary: Check the OP session state (iframe-based)
responses:
'200':
description: Session state
content:
text/plain:
schema: {type: string, enum: [changed, unchanged, error]}
/api/v1/rate_limit:
get:
operationId: getRateLimit
tags: [OAuth]
summary: Inspect current rate-limit status
security:
- bearerAuth: []
responses:
'200':
description: Current rate limit window
'429':
description: Rate limit exceeded
/.well-known/openid-configuration:
get:
operationId: openidConfiguration
tags: [OpenID Connect]
summary: OpenID Connect discovery document
responses:
'200': {description: OIDC provider metadata}
/.well-known/oauth-authorization-server:
get:
operationId: oauthAuthorizationServer
tags: [OAuth]
summary: OAuth 2.0 Authorization Server Metadata (RFC 8414)
responses:
'200': {description: Authorization server metadata}
/.well-known/jwks.json:
get:
operationId: jwks
tags: [OpenID Connect]
summary: JSON Web Key Set for verifying id_token signatures
responses:
'200': {description: JWKS}
components:
securitySchemes:
doximityOAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.doximity.com/oauth/authorize
tokenUrl: https://auth.doximity.com/oauth/token
refreshUrl: https://auth.doximity.com/oauth/token
scopes:
openid: Enables the OpenID Connect id_token to be returned
search: Search the Doximity member directory
dialer: Access to Doximity Dialer functionality
docsgpt:access: Access to DocsGPT
hipaa:identified: Access identified data under HIPAA
jobs:read: Read job data
colleagues:read: Read the member's colleagues
colleagues:write: Modify the member's colleagues
login_context:inferred: Access inferred login context
sessions:linked: Access linked sessions
activities:read:cards: Read activity cards
activities:read:comments: Read activity comments
activities:read:likes: Read activity likes
activities:write:likes: Write activity likes
profile:read:basic: Read basic profile (name, credentials, specialty, photo)
profile:read:email: Read the member's email
profile:read:dialer_phone: Read the member's Dialer phone number
profile:read:experience: Read the member's experience
profile:read:office: Read the member's office information
profile:read:permissions: Read the member's permissions
profile:read:private_contact: Read the member's private contact information
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.doximity.com/.well-known/openid-configuration
clientBasic:
type: http
scheme: basic
description: HTTP Basic with client_id:client_secret (client_secret_basic)
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
TokenResponse:
type: object
properties:
access_token: {type: string}
token_type: {type: string, example: bearer}
expires_in: {type: integer, example: 1800}
refresh_token: {type: string}
scope: {type: string}
id_token: {type: string, description: Signed JWT (RS256)}
OAuthError:
type: object
properties:
error: {type: string, example: invalid_grant}
error_description: {type: string}
UserInfo:
type: object
description: OpenID Connect claims, gated by granted scopes.
properties:
sub: {type: string, description: Stable subject identifier (UUID v4)}
name: {type: string}
given_name: {type: string}
family_name: {type: string}
middle_name: {type: string}
credentials: {type: string}
profile_photo_url: {type: string, format: uri}
profile_uuid: {type: string}
specialty: {type: string}
primary_email: {type: string, format: email}
emails: {type: array, items: {type: string, format: email}}
permissions: {type: array, items: {type: string}}
security:
- doximityOAuth: []