openapi: 3.2.0
info:
title: Cvent REST APIs — Event Cloud Authentication API
description: "Event Cloud scope of the Cvent REST APIs. This document is a TAG-SCOPED SUBSET of the OpenAPI specification Cvent publishes at https://github.com/cvent/rest-sdks/blob/main/cvent-public-spec/openapi.yaml (the source of truth for Cvent's official TypeScript/.NET/Java SDKs). Venue-sourcing, RFP, housing-supplier and travel-supplier tags were removed because they belong to Cvent Hospitality Cloud; every path, operation, parameter, schema and security requirement below is verbatim from Cvent's published spec.\n\n# Introduction\nThe Cvent API Platform is built around REST. We aim to provide intuitive endpoints that can be easily\ndiscovered to help leverage the Cvent platform for your event needs. The RESTful APIs outlined here\nuse JSON-encoded request and response format, along with HTTP codes, to convey processing status of\nrequests received. The Cvent resources are protected using OAuth2.\n\n# Getting Started\n\nIf you're new to the Cvent API Platform, start by reading our\n[Developer Quickstart](https://developers.cvent.com/docs/rest-api/tutorials/developer-quickstart) guide. This will\ngive you an overview of how to authenticate and make requests using our APIs.\n\n## Authentication\n\nThe Cvent REST API uses [OAuth2](https://oauth.net/2/) to authorize requests to the platform. The client\ncredentials authorization flow is supported.\n\n<a name=\"oauth2-auth-code-planner-admin\"></a>\n\nAuthorization code flow is only supported for planner users with the administrator role in Cvent. Developer users\ncannot use authorization code flow.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\nHere's an example of using client credential flow to authorize. You'll supply your application's id and secret to\nmake a [Token](#operation/oauth2Token) request.\n\n```bash\ncurl --location --request POST '{hostName}/{version}/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--header 'Authorization: Basic {api_credentials}' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id={client_id}'\n```\n\n| Key | Description | Value |\n| :---------------- | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |\n| {hostName} | https://api-platform.cvent.com | Location if your account is in the North American datacenter. |\n| | https://api-platform-eur.cvent.com | Location if your account is in the European data center. |\n| {version} | ea | The version of the API you're using. Only `ea` is currently supported. |\n| {api_credentials} | {client_id}:{client_secret} in base64 encoded format | Supply your client id & client credentials in a base 64 encoded format. |\n| {client_id} | Retrieved from your application | Your application's client id. |\n| {client_secret} | Retrieved from your application | Your application's client secret. |\n\nOn a successful call, you'll receive the following response:\n\n```json\n{\n \"access_token\": \"{accessToken}\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\"\n}\n```\n\nThis bearer token is valid for 3600 seconds (60 minutes) and must be used in subsequent calls.\n\n## Endpoints\n\nEndpoints start with `hostName` and `version`.\n\nThe `hostname` will depend on the region that your Cvent account is hosted in. Please see the table\nbelow to identify which hostname you should be using.\n\n| Region |\tHostname |\n|:--------------|:-----------------------------------|\n| North America\t| https://api-platform.cvent.com |\n| Europe | https://api-platform-eur.cvent.com |\n\nThe current `version` of the Cvent API is `ea`.\n\n## Rate Limits\n\nCvent APIs enforce rate limits to ensure platform stability. Your limits depend on your tier: Free,\nStandard, or Premium.\n\n<br />\n\n### Usage Tiers\n\n| Tier | Daily Calls | Calls per Second | Max Burst |\n| -------- | ----------- | ---------------- | --------- |\n| Free | 1,000 | 2 | 1 |\n| Standard | 15,000 | 10 | 10 |\n| Premium | 500,000 | 25 | 25 |\n\n- **Daily calls** define how many requests you can make in a 24-hour period. Quota\n resets at 12 midnight (+0 GMT).\n- **Calls per second** define how many requests you can make in a 1-second window.\n- **Max Burst** defines how many requests you can make at once.\n\nIf you are unsure what usage tier applies to your account, you can check via\n[Get Current Usage Tier](#operation/getUsageTier).\n\nPlease note that these limits may change as the Cvent API Platform evolves.\n\n<br />\n\n### Handling Rate Limits\n\nSometimes, you may exceed your rate limits. When this happens, the API will return a `429 Too Many Requests`. See\n[handling rate limits](https://developers.cvent.com/docs/rest-api/guides/handling-rate-limits) for best practices on how to handle this.\n\n## Pagination\n\nSome APIs use pagination to manage records. Each page of records has a token associated to identify it.\n\nIf an API uses pagination, you’ll find up to three tokens in the response:\n- **currentToken**: Describes the token of the current page.\n- **nextToken**: Provides a token for the next page of records, if one exists.\n- **previousToken**: Provides a token for the previous page of records, if one exists. Not all APIs will return\n this token.\n\nYou specify which page of records to view via the `token` parameter in your API call. To navigate through pages,\ntake the `nextToken` or `previousToken` value and pass it to your next call’s `token` parameter to get the\nrespective page of records. For example, if you made this request:\n\n```bash\ncurl -X GET {hostname}/{version}/contacts?limit=100 \\\n-H 'Accept: application/json' \\\n-H 'Authorization: Bearer {accessToken}'\n```\n\nThe response contains a paging array where you'll find the token information.\n\n```json\n{\n \"paging\": {\n \"currentToken\": \"90c5f062-76ad-4ea4-aa53-00eb698d9262\",\n \"nextToken\": \"3b2359a7-4583-40ed-8afd-67e5f15373d3\",\n \"limit\": 100,\n \"totalCount\": 102,\n \"_links\": {...}\n },\n \"data\": [...]\n}\n```\n\nTake the `nextToken` and use it in the `token` parameter on your subsequent call.\n\n```bash\ncurl -X GET {hostname}/{version}/contacts?limit=100&token=3b2359a7-4583-40ed-8afd-67e5f15373d3 \\\n-H 'Accept: application/json' \\\n-H 'Authorization: Bearer {accessToken}'\n```\n\nWhen the response doesn’t contain a `nextToken` field, you’ve reached the last page. Occasionally, you might\nencounter an empty page at the end of results. This typically happens when the results were evenly divisible.\nEnsure your client code handles the possibility of receiving an empty data array when using the `nextToken`.\n\n## Filtering\n\nUse filters to narrow down results. The filter follows the pattern\n`filter='field' comparisonType 'value'`. The value can be enclosed with single\nquotes (') or double quotes (\").\n\n```bash\nGET {hostName}/{version}/contacts?filter=lastName eq 'Smith'\n````\n\nTo correctly pass a single quote in the filter's value, use double quotes around\nthe string.\n\n```bash\nGET {hostName}/{version}/contacts?filter=lastName eq \"O'Keenan\"\n```\n\nTo correctly pass a double quote in the filter's value, use double quotes around\nthe string and add an escape character `\\` to each quote that is part of the\nstring.\n\n```bash\nGET {hostName}/{version}/events?filter=eventName eq \"\\\"Yearly\\\" Conference\"\n```\n\n## Versioning\n\nChange is inevitable in API development. Planning for it is crucial. We track\nboth backward-compatible and backward-incompatible changes.\n\n<br />\n\n### Backward Compatible Changes\n\nBackward compatible changes will be made often and are intended to avoid\nany adverse impact on our customers. It is highly advisable that when reading\nJSON payloads from Cvent, you are able to handle \"unknown\" attributes that\ncan be added over time. We consider the following changes backward-compatible:\n\n- Adding new resources\n- Adding new optional request parameters to existing operations\n- Adding new attributes to requests or responses\n- Changing the length or format (not type) of resource identifiers. For example, an ID can change from\n \"1234/1234\" to \"1234::1234\".\n- Increasing the length of string fields\n\n<br />\n\n### Backward Incompatible Changes\n\nBackward-incompatible changes are made infrequently, however, they can be\ndisruptive to consumers. Due to this, our APIs are versioned to avoid\ndisruptions to customers. We leverage a URI-based versioning scheme,\nwhich means that a version value is included in the Cvent API URL.\nWhen breaking changes occur, a new version of the API is made available\nwhile the existing version is deprecated but remains available for a\nlimited period of time. We consider the following backward-incompatible changes:\n\n- Adding a new required parameter (query string param or payload attribute)\n- Deleting API resources\n- Deleting any attribute from API responses\n- Changing the data type on any parameter or attribute\n\n## Standards\nAs you begin working with our APIs, it's essential to be aware of standards around\ncountry codes, time formats, and other important details that ensure smooth integration.\nLearn more about our [API Standards](https://developers.cvent.com/docs/rest-api/reference/api-standards)\n"
contact:
name: Cvent Development Platform
url: https://developers.cvent.com/
version: ea
servers:
- url: https://api-platform.cvent.com/ea
- url: https://api-platform-eur.cvent.com/ea
tags:
- name: Authentication
description: Endpoints for obtaining, refreshing, and validating OAuth2 access tokens.
paths:
/oauth2/authorize:
get:
tags:
- Authentication
summary: Get Authorization Code
description: 'Initiates the OAuth2 authorization code flow by directing the user-agent to the Cvent authorization server. The client typically triggers this request via a browser. For the `redirect_uri` HTTPS is required; `http://localhost` is permitted for local testing only. On success, the authorization server redirects the user-agent back to the client''s `redirect_uri` with an authorization code. The client can then exchange that code via [Get Token](#operation/oauth2Token) to obtain an access token.
'
operationId: oauth2Authorize
parameters:
- in: query
name: response_type
description: 'The response type must be code. Indicates the client wants an authorization code (authorization code grant flow).
**Note:** *implicit flow* or the *token* value is not supported at this time.
'
schema:
type: string
enum:
- code
example: code
required: true
- in: query
name: client_id
description: 'The OAuth2 Client application ID.
Must be a pre-registered client created in the developer portal.
'
schema:
type: string
example: ad398u21ijw3s9w3939
required: true
- in: query
name: redirect_uri
description: 'The URL to which the authorization server redirects the browser after authorization has been granted by the user.
A redirect URI must:
* Be an absolute URI.
* Be pre-registered with a client.
* **NOT** include a fragment component.
* Wildcards are **NOT** supported
Requires HTTPS over HTTP except for http://localhost for testing purposes only.
**Note:** App callback URLs such as *com.myclientapp://myclient/redirect* are also supported.
'
schema:
type: string
example: https://example.com/redirect
required: true
- in: query
name: state
description: 'An opaque value the client application adds to the initial request. The authorization server
includes this value when redirecting back to the client.
This value must be used by the client to prevent CSRF attacks.
**Optional** but strongly recommended.
'
schema:
type: string
example: abc123xyz
required: false
- in: query
name: scope
description: 'Can be a combination of any scopes associated with a client. Scopes must be separated by spaces.
Any scope used must be pre-associated with the client or it will be ignored at runtime.
**Note:** If the client doesn''t request any scopes, the authorization server uses all
scopes associated with the client.
'
schema:
type: string
example: event/events:read event/attendees:read
required: false
responses:
'302':
description: Redirect back to calling application.
headers:
Location:
schema:
type: string
description: "**Positive Response**\n\nThe authorization server redirects the user-agent back to the client's redirect URI with the authorization code and state.\nThe code and state must be returned in the query string parameters.\n\n**Negative Responses**\n\n- If client_id and redirect_uri are valid but there are other problems with the request parameters\n(for example, if response_type is not included), the authorization server redirects the error to\nclient's redirect_uri.\n - Location: https://client_redirect_uri?error=invalid_request\n\n- If the client requests 'code' in response_type but does not have permission for these requests,\nthe authorization server should return unauthorized_client to client's redirect_uri.\n - Location: https://client_redirect_uri?error=unauthorized_client\n\n- If the client requests invalid, unknown, malformed scope, the authorization server should return\ninvalid_scope to the client's redirect_uri, as follows.\n - Location: https://client_redirect_uri?error=invalid_scope\n\n- If there is any unexpected error in the server, the authorization server should return\nserver_error to client's redirect_uri. It should not be the HTTP 500 error displayed to\nthe end user in the browser, because this error doesn't get sent to the client.\n - Location: https://client_redirect_uri?error=server_error\n\n- In the rare case where the authorization server encounters an exception in the communication\nprotocol while making any connection to an external identity provider, the authorization\nserver redirects the error to the client's redirect_uri with either of the following messages.\n - Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset\n - Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out\n"
example: https://client_redirect_uri?code=AUTHORIZATION_CODE&state=STATE
'400':
description: The request is missing a required parameter.
/oauth2/token:
post:
tags:
- Authentication
summary: Get Token
description: 'Obtains an access token and, optionally, a refresh token. Read the [Developer Quickstart](https://developers.cvent.com/docs/rest-api/tutorials/developer-quickstart) for an example request.
**Note:** The token endpoint returns refresh_token only when the grant_type is authorization_code.
'
operationId: oauth2Token
parameters:
- in: header
name: Authorization
description: 'The client must pass its client_id and client_secret in the authorization header through Basic HTTP authorization.
An example is `Basic Base64Encode(client_id:client_secret)` where `Base64Encode` means that the client id and secret are base64 encoded.
'
schema:
type: string
example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
required: true
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
grant_type:
description: Controls the OAuth2 grant flow used to obtain tokens.
enum:
- client_credentials
- authorization_code
- refresh_token
example: client_credentials
client_id:
description: 'The OAuth2 Client application ID.
Must be a pre-registered client created in the developer portal.
'
type: string
example: djc98u3jiedmi283eu928
scope:
description: 'Can be a combination of any scopes associated with a client. Any scope requested must be pre-associated with the client or it will be ignored at runtime.
If the client doesn''t request any scopes, the authorization server uses all scopes associated with the client.
**Optional** - Only used if the grant_type is client_credentials.
'
type: string
example: event/events:read event/attendees:read
redirect_uri:
description: 'Must be the same *redirect_uri* that was used to get *authorization_code* in */oauth2/authorize*.
**Required only if grant_type is authorization_code.**
'
type: string
example: https://example.com/redirect
refresh_token:
description: 'The refresh token.
**Note:** The token endpoint returns *refresh_token* only when the grant_type is *authorization_code*.
'
type: string
example: dn43ud8uj32nk2je
code:
description: 'The code that is returned from a successful */oauth2/authorize*.
**Required if grant_type is authorization_code.**
'
type: string
example: AUTHORIZATION_CODE
required:
- grant_type
- client_id
responses:
'200':
description: A successful response returning an access token and a possible refresh token.
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
description: The access token contains scopes and groups and is used to grant access to authorized resources.
example: eyJz9sdfsdfsdfsd
refresh_token:
type: string
description: The refresh token contains the information necessary to obtain a new access token.
example: dn43ud8uj32nk2je
token_type:
type: string
description: The OAuth2 token type. Always `Bearer`.
example: Bearer
expires_in:
type: integer
description: The lifetime in seconds of the access token.
default: 3600
example: 3600
required:
- access_token
- token_type
- expires_in
'400':
description: A bad token response.
content:
application/json:
schema:
type: object
properties:
error_description:
type: string
description: Additional error information, when available.
error:
type: string
description: '**invalid_request**
The request is missing a required parameter, includes an unsupported parameter value (other than unsupported_grant_type), or is otherwise malformed. For example, grant_type is refresh_token but refresh_token is not included.
**invalid_client**
Client authentication failed. For example, when the client includes client_id and client_secret in the authorization header, but there''s no such client with that client_id and client_secret.
**invalid_grant**
Refresh token has been revoked.
Authorization code has been consumed already or does not exist.
**unauthorized_client**
Client is not allowed for code grant flow or for refreshing tokens.
**unsupported_grant_type**
Returned if grant_type is anything other than authorization_code or refresh_token.
'
enum:
- invalid_request
- invalid_client
- invalid_grant
- unauthorized_client
- unsupported_grant_type
example: invalid_request
'401':
description: Client authentication failed. The credentials provided in the Authorization header are invalid or missing.
/token-validation:
get:
tags:
- Authentication
summary: Validate Token
description: Verifies presented authentication token is valid.
operationId: validateToken
security:
- OAuth2.clientCredentials: []
- OAuth2.authorizationCode: []
parameters: []
responses:
'200':
$ref: '#/components/responses/ValidToken'
'400':
$ref: '#/components/responses/BadRequest1'
'401':
$ref: '#/components/responses/Unauthorized1'
'403':
$ref: '#/components/responses/Forbidden1'
'429':
$ref: '#/components/responses/TooManyRequests1'
deprecated: false
externalDocs:
description: More about OAuth2 authorization code support for administrators
url: '#oauth2-auth-code-planner-admin'
components:
responses:
Forbidden1:
description: You do not have access to the resource
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 403
message: Access Forbidden
BadRequest1:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
message: Bad Request
TooManyRequests1:
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 429
message: Limit Exceeded
ValidToken:
description: A confirmation message that the token is valid
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ValidToken'
Unauthorized1:
description: Bad or expired token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 401
message: Unauthorized
schemas:
ValidToken:
title: Valid Token
description: Validity status of an authentication token.
type: object
properties:
tokenValid:
type: boolean
description: True indicates the presented authentication token is valid.
example: true
statusCode:
type: integer
description: Supplementary status code. Typically will be 200 for a success case.
example: 200
ErrorResponseBase:
title: ErrorResponseBase
type: object
description: Represents an error response with no additional details.
required:
- code
- message
properties:
code:
type: integer
description: The HTTP status code representing the error.
example: 400
message:
type: string
description: A brief description of the error.
example: Bad Request
target:
type: string
description: The target resource of the error.
example: example target
ErrorResponse:
title: ErrorResponse
description: Represents an error response with additional details of cascading error messages.
allOf:
- $ref: '#/components/schemas/ErrorResponseBase'
type: object
required:
- code
- message
properties:
details:
type: array
items:
$ref: '#/components/schemas/ErrorResponseBase'
description: Additional details of cascading error messages.
securitySchemes:
OAuth2.authorizationCode:
type: oauth2
description: OAuth2 Authorization Code Flow.
flows:
authorizationCode:
authorizationUrl: https://api-platform.cvent.com/ea/oauth2/authorize
tokenUrl: https://api-platform.cvent.com/ea/oauth2/token
scopes:
account/hooks:delete: Allows the deletion of hooks.
account/hooks:read: Allows the reading of hooks.
account/hooks:write: Allows the creation/updation of hooks.
account/user-groups:delete: Allows deletion for user groups
account/user-groups:read: Allows the reading of user groups
account/user-groups:write: Allows the writing of user groups
account/users:delete: Allows the deletion of User
account/users:read: Allows the reading of User, User Group
account/users:write: Allows the creation/updating of User
appointments/appointment-attendees:read: Allows the reading of appointment attendees and their related entities.
appointments/appointment-events:read: Allows the reading of appointment events and their related entities.
appointments/appointment-types:read: Allows the reading of appointment types and their related entities.
appointments/appointments:read: Allows the reading of appointment and their related entities.
appointments/appointments:write: Allows the writing of appointments and their related entities.
appointments/available-times:read: Allows the reading of available times.
appointments/locations:read: Allows the reading of appointment locations and their related entities.
attendee-insights/attendee-insights:read: Allows the reading of engagement scores (attendee insights).
attendee-insights/scores:read: Allows the reading of scores.
attendee-insights/stats:read: Allows the reading of engagement score (attendee insight) stats.
budget/budget-items:delete: Allows the deletion of budget items
budget/budget-items:read: Allows the reading of all budget items
budget/budget-items:write: Allows creation/updation of budget item
budget/budget-totals:read: Allows the reading of all event budget totals
budget/budget-vendors:read: Allows reading of account-level budget vendors.
budget/cards:read: Allows the reading of cards
budget/currency-conversion-rate:delete: Allows deletion of currency conversion rate for currency.
budget/currency-conversion-rate:read: Allows reading of currency conversion rate for currency.
budget/currency-conversion-rate:write: Allows creation/update of currency conversion rate for currency.
budget/payments:delete: Allows deletion of payments.
budget/payments:read: Allows reading of payment for budget item.
budget/payments:write: Allows creation of payment in a budget item.
budget/transactions:delete: Allows delete card transactions.
budget/transactions:read: Allows the reading of all card's transactions
budget/transactions:write: Allows creation of card transactions.
business-transient/bids:read: Allows the reading of BT Bid data
business-transient/proposals:read: Allows the reading of BT Proposal data
business-travel/bids:read: Allows the reading of BT Bid data
business-travel/proposals:read: Allows the reading of BT Proposal data
compliance/communications:read: Allows the reading of communication compliance
compliance/communications:write: Allows the writing of communication compliance
email/bounces:read: Allow the reading of email bounces.
email/email-status:read: Allows the reading of email statuses.
email/emails:read: Allows the reading of emails.
eMarketing/campaigns:read: Allows the reading of campaigns.
emarketing/emarketing-email-status:read: Allows the reading of eMarketing email statuses.
eMarketing/eMarketing-email-templates:read: Allows the reading of email-templates.
eMarketing/eMarketing-send-emails:write: Allows the writing of eMarketing emails.
event/admission-items:read: Allows the reading of admission items
event/air-request:read: Allow reading the air request or air actual detail for attendees.
event/alternate-travel:read: Allow reading the alternate travel answers for attendees.
event/attendance-durations:read: Allows the read of Duration records
event/attendee-activities-metadata:delete: Allows the deletion of attendees activities metadata.
event/attendee-activities-metadata:read: Allows the reading of attendee activities metadata.
event/attendee-activities-metadata:write: Allows the creation/updating of attendees activities metadata.
event/attendee-activities:read: Allows the reading of attendee activities.
event/attendee-activities:write: Allows the writing of attendee activities.
event/attendee-credits:read: Allows the reading of attendee credits.
event/attendee-links:delete: Allows the deletion of attendee links
event/attendee-links:read: Allows the reading of attendee links
event/attendee-links:write: Allows the creation of attendee links
event/attendee-messages:read: Allows the reading of attendee messages
event/attendees:read: Allows the reading of attendees.
event/attendees:write: Allows the creation of an attendee in an event.
event/audience-segments:read: Allows the reading of audience segments.
event/audience-segments:write: Allows the creation/updating/deletion of audience segments.
event/contact-groups:read: Allows the reading of contact groups.
event/contact-groups:write: Allows the creation/updating of contact groups.
event/contact-types:read: Allows the reading of contact types.
event/contacts:delete: Allows the deletion of contacts.
event/contacts:read: Allows the reading of contacts.
event/contacts:write: Allows the creation/updating of contacts.
event/contacts:write-sensitive: Allows the creation/updating of sensitive data related to contacts.
event/custom-fields:read: Allows the reading of custom fields
event/custom-fields:write: Allows the writing of custom fields
event/discounts:write: Allows the writing of discounts
event/donation-items:read: Allows the reading of donation items.
event/event-discounts:read: Allows the reading of event discounts.
event/event-discounts:write: Allows the writing of event discounts.
event/event-email-status:read: Allows
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cvent-event-cloud/refs/heads/main/openapi/cvent-event-cloud-authentication-api-openapi.yml