RingCentral OAuth 2.0 / OpenID Connect API
Public OAuth 2.0 and OpenID Connect Resources
OpenAPI Specification
openapi: 3.0.3
info:
title: RingCentral Adaptive Cards OAuth 2.0 / OpenID Connect API
description: RingCentral API specification
version: 1.0.58-20240529-47eda8bd
contact:
name: RingCentral Developers Support
url: https://developers.ringcentral.com/support
termsOfService: https://www.ringcentral.com/legal/apilitos.html
license:
name: RingCentral API License Agreement
url: https://www.ringcentral.com/legal/apilitos.html
servers:
- url: https://platform.ringcentral.com
description: Production API entry point
- url: https://media.ringcentral.com
description: Production Media entry point
- url: https://platform.devtest.ringcentral.com
description: Developer sandbox API entry point
- url: https://platform.devtest.ringcentral.com
description: Developer sandbox Media entry point
security:
- OAuth2: []
tags:
- name: OAuth 2.0 / OpenID Connect
description: Public OAuth 2.0 and OpenID Connect Resources
paths:
/restapi/oauth/token:
post:
tags:
- OAuth 2.0 / OpenID Connect
summary: OAuth 2.0 Token Endpoint
description: 'Returns access (and potentially refresh) tokens for making API requests.
For confidential client application types
this endpoint requires client authentication using one of the supported
methods (`client_secret_basic`, `client_secret_jwt` or `private_key_jwt`)
For non-confidential client application types
the client identifier must be provided via `client_id` request attribute.
'
operationId: getToken
security:
- {}
- OauthBasicScheme: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/GetTokenRequest'
responses:
'200':
description: Access/Refresh Tokens
content:
application/json:
schema:
$ref: '#/components/schemas/TokenInfo'
'400':
$ref: '#/components/responses/OauthInvalidRequest'
'415':
description: Unsupported Media Type
'429':
description: Request rate exceeded
x-throttling-group: Auth
/restapi/oauth/authorize:
get:
tags:
- OAuth 2.0 / OpenID Connect
summary: OAuth 2.0 Authorization Endpoint
description: 'Performs Authentication of the End-User by sending the User Agent to the Authorization Server''s
Authorization Endpoint for Authentication and Authorization,
using request parameters defined by OAuth 2.0 [RFC-6749](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1)
and additional parameters and parameter values defined by
[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
This is the version that uses HTTP `GET` method.
'
operationId: authorize
parameters:
- $ref: '#/components/parameters/OauthClientId'
- name: response_type
in: query
required: true
description: 'Determines authorization flow type. The only supported value is `code` which corresponds to OAuth 2.0 "Authorization Code Flow"
'
schema:
type: string
enum:
- code
- name: redirect_uri
in: query
required: false
description: 'This is the URI where the Authorization Server redirects the User Agent to at the end of the authorization flow.
The value of this parameter must exactly match one of the URIs registered for this client application.
This parameter is required if there are more than one redirect URIs registered for the app.
'
schema:
type: string
format: uri
- name: state
in: query
required: false
description: 'An opaque value used by the client to maintain state between the request and callback.
The authorization server includes this value when redirecting the User Agent back
to the client. The parameter SHOULD be used for preventing cross-site request forgery attacks.
'
schema:
type: string
- name: scope
in: query
required: false
description: The list of space separated application permissions (OAuth scopes)
schema:
type: string
- name: display
in: query
required: false
description: 'Specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User.
'
schema:
$ref: '#/components/schemas/DisplayModesEnum'
- name: prompt
in: query
required: false
description: 'Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for
re-authentication and consent. The defined values are:
- `login` - RingCentral native login form,
- `sso` - Single Sign-On login form,
- `consent` - form to show the requested scope and prompt user for consent.
Either `login` or `sso` (or both) must be specified. The default
value is `login sso`
'
schema:
type: string
default: login sso
- name: ui_locales
in: query
required: false
description: 'End-User''s preferred languages and scripts for the user interface, represented as a space-separated list of
[RFC-5646](https://datatracker.ietf.org/doc/html/rfc5646) language tag values, ordered by preference.
If this parameter is provided, its value overrides ''Accept-Language'' header value and ''localeId'' parameter value (if any)
'
schema:
type: string
example: en-US
- name: localeId
in: query
deprecated: true
description: 'DEPRECATED: `ui_locales` parameter should be used instead'
schema:
type: string
example: en-US
- name: code_challenge
in: query
required: false
description: 'The code challenge value as defined by the PKCE specification -
[RFC-7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://datatracker.ietf.org/doc/html/rfc7636)
'
schema:
type: string
- name: code_challenge_method
in: query
required: false
description: 'The code challenge method as defined by by the PKCE specification -
[RFC-7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://datatracker.ietf.org/doc/html/rfc7636)
'
schema:
$ref: '#/components/schemas/CodeChallengeMethodEnum'
- name: nonce
in: query
required: false
description: 'String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.
'
schema:
type: string
- name: ui_options
in: query
required: false
description: 'Login form user interface options (space-separated). By default, the UI options that are registered for this client application will be used
'
schema:
type: string
- name: login_hint
in: query
required: false
description: Hint to the Authorization Server about the login identifier the End-User might use to log in.
schema:
type: string
- $ref: '#/components/parameters/OauthBrandId'
responses:
'302':
description: Successful response, HTTP redirect to login form
headers:
Location:
description: Full URL of the redirect target locations
schema:
type: string
format: uri
'400':
$ref: '#/components/responses/OauthInvalidRequest'
callbacks:
requestProcessed:
'{$request.query.redirect_uri}':
get:
parameters:
- $ref: '#/components/parameters/OauthRedirectCode'
- $ref: '#/components/parameters/OauthRedirectState'
- $ref: '#/components/parameters/OauthRedirectError'
responses:
'200':
description: Callback successfully accepted
x-throttling-group: Auth
post:
tags:
- OAuth 2.0 / OpenID Connect
summary: OAuth 2.0 Authorization Endpoint (POST)
description: 'Performs Authentication of the End-User by sending the User Agent to the Authorization Server''s
Authorization Endpoint for Authentication and Authorization,
using request parameters defined by OAuth 2.0 [RFC-6749](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1)
and additional parameters and parameter values defined by
[OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint).
This is the version that uses HTTP `POST` method.
'
operationId: authorize2
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/AuthorizeRequest'
responses:
'302':
description: Successful response, HTTP redirect to login form
headers:
Location:
description: Full URL of the redirect target locations
schema:
type: string
format: uri
'400':
$ref: '#/components/responses/OauthInvalidRequest'
callbacks:
requestProcessed:
'{$request.body#/redirect_uri}':
get:
parameters:
- $ref: '#/components/parameters/OauthRedirectCode'
- $ref: '#/components/parameters/OauthRedirectState'
- $ref: '#/components/parameters/OauthRedirectError'
responses:
'200':
description: Callback successfully accepted
x-throttling-group: Auth
/restapi/oauth/revoke:
post:
tags:
- OAuth 2.0 / OpenID Connect
summary: OAuth 2.0 Token Revocation Endpoint
description: 'Revokes all active access/refresh tokens and invalidates the OAuth session basing on token provided.
The `token` parameter may be passed in query string or body and may represent access or refresh token.
This endpoint is defined by [RFC-7009 "OAuth 2.0 Token Revocation"](https://datatracker.ietf.org/doc/html/rfc7009)
For confidential client application types
this endpoint requires client authentication using one of the supported
methods (`client_secret_basic`, `client_secret_jwt` or `private_key_jwt`)
'
operationId: revokeToken
parameters:
- name: token
in: query
description: Access or refresh token to be revoked (along with the entire OAuth session)
required: false
schema:
type: string
security:
- {}
- OauthBasicScheme: []
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RevokeTokenRequest'
required: false
responses:
'200':
description: Successful response
'400':
$ref: '#/components/responses/OauthInvalidRequest'
x-throttling-group: Auth
components:
schemas:
IvrPinTokenRequest:
title: IVR Pin
type: object
description: 'Token endpoint request parameters used in the "IVR Pin" authorization flow with the `ivr_pin` grant type
'
properties:
grant_type:
type: string
description: Grant type
enum:
- ivr_pin
ivr_pin:
type: string
description: For `ivr_pin` grant type only. User's IVR pin.
CodeChallengeMethodEnum:
type: string
description: 'The code challenge method as defined by the PKCE specification -
[RFC-7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://datatracker.ietf.org/doc/html/rfc7636)
'
enum:
- plain
- S256
default: plain
DeviceCodeTokenRequest:
title: Device Token
type: object
description: 'Token endpoint request parameters used in the "Device Authorization" flow
with the `urn:ietf:params:oauth:grant-type:device_code` grant type
'
properties:
grant_type:
type: string
description: Grant type
enum:
- urn:ietf:params:oauth:grant-type:device_code
device_code:
type: string
description: 'For `urn:ietf:params:oauth:grant-type:device_code` grant type only.
The device verification code as defined by [RFC-8628](https://datatracker.ietf.org/doc/html/rfc8628#section-3.4)
'
RopcTokenRequest:
title: Password (ROPC)
type: object
description: 'Token endpoint request parameters used in the "Password" (also known as "Resource Owner Password Credentials" - ROPC)
authorization flow with the `password` grant type
'
properties:
grant_type:
type: string
description: Grant type
enum:
- password
username:
type: string
description: 'For `password` grant type only. User login name: email or phone number in E.164 format
'
password:
type: string
description: For `password` grant type only. User's password
format: password
extension:
type: string
deprecated: true
description: 'For `password` grant type only. Optional. Extension short number. If a company number
is specified as a username, and extension is not specified, the
server will attempt to authenticate client as main company administrator
DEPRECATED: use extension number embedded into username string like `+16501234567*101`
'
pin:
type: string
deprecated: true
description: 'IVR pin for pin-based authentication.
DEPRECATED: use a dedicated `ivr_pin` grant type instead
'
GetTokenRequest:
allOf:
- $ref: '#/components/schemas/ClientAuthJwtModel'
- $ref: '#/components/schemas/BaseTokenRequest'
- anyOf:
- $ref: '#/components/schemas/AuthCodeTokenRequest'
- $ref: '#/components/schemas/RopcTokenRequest'
- $ref: '#/components/schemas/JwtTokenRequest'
- $ref: '#/components/schemas/RefreshTokenRequest'
- $ref: '#/components/schemas/IvrPinTokenRequest'
- $ref: '#/components/schemas/DeviceCodeTokenRequest'
- $ref: '#/components/schemas/ClientCredentialsTokenRequest'
- $ref: '#/components/schemas/OtpTokenRequest'
- $ref: '#/components/schemas/GuestTokenRequest'
discriminator:
propertyName: grant_type
mapping:
authorization_code: '#/components/schemas/AuthCodeTokenRequest'
password: '#/components/schemas/RopcTokenRequest'
urn:ietf:params:oauth:grant-type:jwt-bearer: '#/components/schemas/JwtTokenRequest'
partner_jwt: '#/components/schemas/JwtTokenRequest'
refresh_token: '#/components/schemas/RefreshTokenRequest'
ivr_pin: '#/components/schemas/IvrPinTokenRequest'
urn:ietf:params:oauth:grant-type:device_code: '#/components/schemas/DeviceCodeTokenRequest'
client_credentials: '#/components/schemas/ClientCredentialsTokenRequest'
otp: '#/components/schemas/OtpTokenRequest'
guest: '#/components/schemas/GuestTokenRequest'
ApiErrorWithParameter:
description: 'The error model with additional attributes which can be used for HTTP 400/409
This is a deprecated model: "ApiError" model can be used instead with arbitrary additional parameters
'
allOf:
- $ref: '#/components/schemas/ApiError'
- type: object
properties:
parameterName:
type: string
description: The name of the API parameter/attribute which caused the error
parameterValue:
type: string
description: The value of the API parameter/attribute which caused the error
BaseTokenRequest:
type: object
required:
- grant_type
properties:
grant_type:
type: string
description: Grant type
enum:
- authorization_code
- password
- refresh_token
- client_credentials
- urn:ietf:params:oauth:grant-type:jwt-bearer
- urn:ietf:params:oauth:grant-type:device_code
- device_certificate
- partner_jwt
- guest
- personal_jwt
- otp
- ivr_pin
scope:
type: string
description: 'The list of application permissions (OAuth scopes) requested.
By default, it includes all permissions configured on
the client application registration
'
client_id:
type: string
description: 'The registered identifier of a client application.
Used to identify a client ONLY if the client authentication is not required and
corresponding credentials are not provided with this request
'
example: AZwEVwGEcfGet2PCouA7K6
endpoint_id:
type: string
description: 'The unique identifier of a client application instance. If not
specified, the derived or auto-generated value will be used
'
access_token_ttl:
maximum: 3600
minimum: 600
type: integer
description: Access token lifetime in seconds
format: int32
default: 3600
refresh_token_ttl:
maximum: 604800
type: integer
description: Refresh token lifetime in seconds
format: int32
default: 604800
RevokeTokenRequest:
allOf:
- type: object
required:
- token
properties:
token:
type: string
description: Access or refresh token to be revoked (along with the entire OAuth session)
- $ref: '#/components/schemas/ClientAuthJwtModel'
ApiError:
type: object
description: Generalized API error structure suitable for any error type
required:
- errorCode
- message
properties:
errorCode:
type: string
description: Logical error code (typically, 3 letters followed with number, dash separated)
example: XXX-123
message:
type: string
description: User-friendly error message
example: Something went wrong
additionalProperties: true
ClientCredentialsTokenRequest:
title: Client Credentials
allOf:
- type: object
description: Token endpoint request parameters used in the "Client Credentials" authorization flow with the `client_credentials` grant type
properties:
grant_type:
type: string
description: Grant type
enum:
- client_credentials
- anyOf:
- type: object
required:
- account_id
properties:
account_id:
type: string
description: RingCentral internal account ID
- type: object
required:
- brand_id
properties:
partner_account_id:
type: string
description: The ID of the account on RingCentral partner's side
brand_id:
type: string
description: RingCentral Brand identifier.
ClientAuthJwtModel:
type: object
properties:
client_assertion_type:
type: string
enum:
- urn:ietf:params:oauth:client-assertion-type:jwt-bearer
description: 'Client assertion type for the `client_secret_jwt` or `private_key_jwt` client authentication types,
as defined by [RFC-7523](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2).
This parameter is mandatory if the client authentication is required and a client decided to use one of these authentication types
'
client_assertion:
type: string
description: 'Client assertion (JWT) for the `client_secret_jwt` or `private_key_jwt` client authentication types,
as defined by [RFC-7523](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2).
This parameter is mandatory if the client authentication is required and a client decided to use one of these authentication types
'
RefreshTokenRequest:
title: Refresh Token
type: object
description: 'Token endpoint request parameters used in the "Refresh Token" flow
with the `refresh_token` grant type
'
properties:
grant_type:
type: string
description: Grant type
enum:
- refresh_token
refresh_token:
type: string
description: 'For `refresh_token` grant type only. Previously issued refresh token.
'
JwtTokenRequest:
title: JWT-Bearer
type: object
description: 'Token endpoint request parameters used in the "Personal JWT", "JWT Bearer" and "Partner JWT" authorization flows
with the `urn:ietf:params:oauth:grant-type:jwt-bearer` and `partner_jwt` grant types
'
properties:
grant_type:
type: string
description: Grant type
enum:
- urn:ietf:params:oauth:grant-type:jwt-bearer
- partner_jwt
assertion:
type: string
description: 'For `urn:ietf:params:oauth:grant-type:jwt-bearer` or `partner_jwt` grant types only.
Authorization grant assertion (JWT)
as defined by [RFC-7523](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1).
'
DisplayModesEnum:
type: string
description: 'Specifies how the Authorization Server displays the authentication and consent user interface pages to the End-User.
'
enum:
- page
- popup
- touch
- mobile
default: page
AuthCodeTokenRequest:
title: Authorization Code
type: object
description: 'Token endpoint request parameters used in the "Authorization Code" and "Authorization code with PKCE" flows
with the `authorization_code` grant type
'
properties:
grant_type:
type: string
description: Grant type
enum:
- authorization_code
code:
type: string
description: For `authorization_code` grant type only. User's authorization code
redirect_uri:
type: string
format: uri
description: 'For `authorization_code` grant type only. This is a callback URI which determines where the response
is sent. The value of this parameter must exactly match one of
the URIs you have provided for your app upon registration
'
code_verifier:
type: string
description: 'For `authorization_code` grant type only.
The code verifier as defined by the PKCE specification -
[RFC-7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://datatracker.ietf.org/doc/html/rfc7636)
'
ParameterizedErrorResponseModel:
type: object
description: Standard error response which may include parameterized errors
required:
- errors
properties:
errors:
type: array
description: The array of errors (there will be just one in the most of the cases)
minItems: 1
items:
$ref: '#/components/schemas/ApiErrorWithParameter'
GuestTokenRequest:
title: Guest
type: object
description: Token endpoint request parameters used in the "Guest" authorization flow with the `guest` grant type
properties:
grant_type:
type: string
description: Grant type
enum:
- guest
brand_id:
type: string
description: RingCentral Brand identifier.
resource_type:
type: string
description: Resource type for the guest access.
resource:
type: string
description: Resource URL for the guest access.
OtpTokenRequest:
title: One-time Password (OTP)
type: object
description: Token endpoint request parameters used in the "One-time Password" (OTP) authorization flow with the `otp` grant type
properties:
grant_type:
type: string
description: Grant type
enum:
- otp
code:
type: string
description: 'For `otp` grant type only.
One-time password code
'
AuthorizeRequest:
type: object
required:
- client_id
- response_type
properties:
response_type:
type: string
description: 'Determines authorization flow type. The only supported value is `code` which corresponds to OAuth 2.0 "Authorization Code Flow"
'
enum:
- code
redirect_uri:
type: string
format: uri
description: 'This is the URI where the Authorization Server redirects the User Agent to at the end of the authorization flow.
The value of this parameter must exactly match one of the URIs registered for this client application.
This parameter is required if there are more than one redirect URIs registered for the app.
'
client_id:
type: string
description: The registered identifier of a client application
example: AZwEVwGEcfGet2PCouA7K6
state:
type: string
description: 'An opaque value used by the client to maintain state between the request and callback.
The authorization server includes this value when redirecting the User Agent back
to the client. The parameter SHOULD be used for preventing cross-site request forgery attacks.
'
scope:
type: string
description: The list of requested OAuth scopes (space separated)
display:
$ref: '#/components/schemas/DisplayModesEnum'
prompt:
type: string
description: 'Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for
re-authentication and consent. The defined values are:
- `login` - RingCentral native login form,
- `sso` - Single Sign-On login form,
- `consent` - form to show the requested scope and prompt user for consent.
Either `login` or `sso` (or both) must be specified. The default
value is `login sso`
'
default: login sso
ui_locales:
type: string
description: 'End-User''s preferred languages and scripts for the user interface, represented as a space-separated list of
[RFC-5646](https://datatracker.ietf.org/doc/html/rfc5646) language tag values, ordered by preference.
If this parameter is provided, its value overrides ''Accept-Language'' header value and ''localeId'' parameter value (if any)
'
example: en-US
code_challenge:
type: string
description: 'The code challenge value as defined by the PKCE specification -
[RFC-7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://datatracker.ietf.org/doc/html/rfc7636)
'
code_challenge_method:
$ref: '#/components/schemas/CodeChallengeMethodEnum'
nonce:
type: string
description: 'String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.
'
ui_options:
type: string
description: 'Login form user interface options (space-separated). By default, the UI options that are registered for this client application will be used
'
login_hint:
type: string
description: Hint to the Authorization Server about the login identifier the End-User might use to log in.
brand_id:
type: string
description: 'RingCentral Brand identifier. If it is not provided in the request,
server will try to determine brand from the client application profile.
'
example: '1210'
accept_language:
type: string
deprecated: true
TokenInfo:
type: object
required:
- access_token
- expires_in
- scope
- token_type
properties:
access_token:
type: string
description: OAuth access token to pass to subsequent API requests
example: U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw
expires_in:
type: integer
format: int32
description: Access token TTL (time-to-live) in seconds
example: 7199
refresh_token:
type: string
description: 'OAuth refresh token (if issued)
'
example: U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w
refresh_token_expires_in:
type: integer
format: int32
description: Refresh token TTL (time-to-live) in seconds
example: 604799
scope:
type: string
description: 'The list of space separated application permissions (OAuth scopes)
'
example: AccountInfo CallLog ExtensionInfo Messages SMS
token_type:
type: string
description: Type of the token. The only supported value is `bearer`. This value should be used when specifying access token in `Authorization` header of subsequent API requests
enum:
- bearer
example: bearer
owner_id:
type: string
description: Token owner's identifier. Contains RingCentral user (extension) ID
example: '256440016'
endpoint_id:
type: string
description: 'Client application instance identifier that matches the value provided by the client,
or generated by the server if a client has not provided this value
'
example: 8zXq6oaLT7WvwWITlGiA1A
id_token:
type: string
description: OpenID Connect ID token (if OpenID Connect flow was activated during authorization)
session_expires_in:
type: integer
format: int32
description: 'Remaining time in seconds until session expiration due to absolute timeout.
Returned only if absolute session timeout is enforced
'
session_expiration_time:
type: string
format: date-time
description: 'Absolute value of session expiration time in ISO date formatted string.
Returned only if absolute session timeout is enforced
'
example: '2023-04-01T12:00:01Z'
session_id:
type: string
description: OAuth session ID
session_idle_timeout:
type: integer
format: int32
description: 'Nominal value of session idle timeout in seconds.
Returned only if idle session timeout is enforced
'
parameters:
OauthRedirectCode:
name: code
in: query
required: false
description: 'The authorization code generated by the authorization server.
REQUIRED if the authorization was successful.
'
schema:
type: string
OauthRedirectState:
name: state
in: query
required: false
description: 'The exact value of the `state` parameter received from the client (if provided).
'
schema:
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ringcentral/refs/heads/main/openapi/ringcentral-oauth-2-0-openid-connect-api-openapi.yml