{"openapi":"3.1.0","info":{"title":"Calendly OAuth","version":"1.0.0"},"paths":{"/oauth/token":{"post":{"operationId":"oAuth_post-oauth-refresh-token","summary":"Get Access Token","description":"Use Access Tokens to access Calendly resources on behalf of an authenticated user.\n\nTo make a call to this endpoint:\n\n* Include `client_id` as a body parameter.\n\n* For the `authorization_code` grant, include the `code_verifier` that matches the `code_challenge` you sent to the authorization endpoint.\n\n* If your app runs on a server, also pass `client_id` and `client_secret` with the Basic HTTP Authorization header.\n\nNote:\n\n* Access Tokens expire after 2 hours.\n\n* Refresh Tokens don't expire until they are used.\n\n* Only 8 oauth tokens per user can be requested within a span of 1 minute","tags":["oAuth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/tokenResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post-oauth-refresh-tokenRequestBadRequestError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post-oauth-refresh-tokenRequestTooManyRequestsError"}}}}},"requestBody":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth_post-oauth-refresh-token_Request"}}}},"security":[{"basicAuth":[]}]}},"/oauth/authorize":{"get":{"operationId":"oAuth_get-oauth-authorize","summary":"Get Authorization Code","description":"The **Authorization Code** is a temporary code that your client exchanges for an access token.\n\n## PKCE flow (required)\n\nEvery OAuth app must use PKCE conforming to RFC 7636, with the `S256` method. If the request does not include a `code_challenge`, it fails. For more information, see [this guide](https://oauth.net/2/pkce/). For a JavaScript example, see [pkce-vanilla-js](https://github.com/aaronpk/pkce-vanilla-js).\n\nTo receive an Authorization Code:\n\n* Generate a `CODE_VERIFIER`\n* Build a `CODE_CHALLENGE`\n* Redirect the user to Calendly's authorization page with the `client_id`, `redirect_uri`, and `code_challenge` replaced with your application's `client_id`, `redirect_uri`, and the `code_challenge` generated in the step above (see example below). Note that this url must be requested using a web browser.\n\n```\nhttps://auth.calendly.com/oauth/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=com.site.app://auth/calendly&code_challenge_method=S256&code_challenge=CODE_CHALLENGE\n```\n\nAfter the user grants access, they will be redirected back to your app with the Authorization Code:\n\n```\ncom.site.app://auth/calendly?code=f04281d639d8248435378b0365de7bd1f53bf452eda187d5f1e07ae7f04546d6\n```","tags":["oAuth"],"parameters":[{"name":"client_id","in":"query","description":"The ID provided by Calendly for the web application","required":true,"schema":{"type":"string"}},{"name":"response_type","in":"query","description":"The response type (which is always \"code\")","required":true,"schema":{"$ref":"#/components/schemas/OauthAuthorizeGetParametersResponseType"}},{"name":"redirect_uri","in":"query","description":"The redirect URI for your OAuth application","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","description":"The PKCE code challenge method. Use `S256`.","required":true,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","description":"The PKCE code challenge, built from your code verifier with SHA-256. Required for every app.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth_get-oauth-authorize_Response_200"}}}}}}},"/oauth/introspect":{"post":{"operationId":"oAuth_post-oauth-introspect","summary":"Introspect Access/Refresh Token","description":"Use this endpoint to introspect an access/refresh token.","tags":["oAuth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth_post-oauth-introspect_Response_200"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post-oauth-introspectRequestBadRequestError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","description":"The ID provided by Calendly for the web application"},"client_secret":{"type":"string","description":"The secret provided by Calendly"},"token":{"type":"string","description":"The access/refresh token provided by Calendly"}},"required":["client_id","client_secret","token"]}}}}}},"/oauth/revoke":{"post":{"operationId":"oAuth_post-oauth-revoke","summary":"Revoke Access/Refresh Token","description":"Use this endpoint to revoke an access/refresh token.","tags":["oAuth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth_post-oauth-revoke_Response_200"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post-oauth-revokeRequestBadRequestError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post-oauth-revokeRequestForbiddenError"}}}}},"requestBody":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string","description":"The ID provided by Calendly for the web application"},"client_secret":{"type":"string","description":"The secret provided by Calendly"},"token":{"type":"string","description":"The access/refresh token provided by Calendly"}},"required":["client_id","client_secret","token"]}}}}}}},"tags":[{"name":"oAuth"}],"servers":[{"url":"https://auth.calendly.com","description":"https://auth.calendly.com"}],"components":{"schemas":{"WebTokenRequestWithCodeGrantType":{"type":"string","enum":["authorization_code"],"description":"The method used to retrieve an access token","title":"WebTokenRequestWithCodeGrantType"},"webTokenRequestWithCode":{"type":"object","properties":{"grant_type":{"$ref":"#/components/schemas/WebTokenRequestWithCodeGrantType","description":"The method used to retrieve an access token"},"code":{"type":"string","description":"The authorization code from an OAuth response"},"redirect_uri":{"type":"string","format":"uri","description":"The redirect URI. Note this must be the same as the **redirect_uri** passed in the authorization request."}},"required":["grant_type","code","redirect_uri"],"description":"The Authorization Code token request for web apps.","title":"webTokenRequestWithCode"},"WebTokenRequestWithRefreshTokenGrantType":{"type":"string","enum":["refresh_token"],"description":"The method used to retrieve an access token","title":"WebTokenRequestWithRefreshTokenGrantType"},"webTokenRequestWithRefreshToken":{"type":"object","properties":{"grant_type":{"$ref":"#/components/schemas/WebTokenRequestWithRefreshTokenGrantType","description":"The method used to retrieve an access token"},"refresh_token":{"type":"string","description":"The refresh token received from previous access token requests. This is used for the refresh_token grant type."}},"required":["grant_type","refresh_token"],"description":"The Refresh Token request for a token for web apps.","title":"webTokenRequestWithRefreshToken"},"NativeTokenRequestWithCodeGrantType":{"type":"string","enum":["authorization_code"],"description":"The method used to retrieve an access token","title":"NativeTokenRequestWithCodeGrantType"},"nativeTokenRequestWithCode":{"type":"object","properties":{"grant_type":{"$ref":"#/components/schemas/NativeTokenRequestWithCodeGrantType","description":"The method used to retrieve an access token"},"client_id":{"type":"string","description":"The ID provided by Calendly for the web application"},"code":{"type":"string","description":"The authorization code from an OAuth response"},"redirect_uri":{"type":"string","format":"uri","description":"The redirect URI. Note this must be the same as the **redirect_uri** passed in the authorization request."},"code_verifier":{"type":"string","description":"The code verifier generated during the authorization request"}},"required":["grant_type","client_id","code","redirect_uri","code_verifier"],"description":"Token request for native apps using authorization code","title":"nativeTokenRequestWithCode"},"NativeTokenRequestWithRefreshTokenGrantType":{"type":"string","enum":["refresh_token"],"description":"The method used to retrieve an access token","title":"NativeTokenRequestWithRefreshTokenGrantType"},"nativeTokenRequestWithRefreshToken":{"type":"object","properties":{"grant_type":{"$ref":"#/components/schemas/NativeTokenRequestWithRefreshTokenGrantType","description":"The method used to retrieve an access token"},"client_id":{"type":"string","description":"The ID provided by Calendly for the web application"},"refresh_token":{"type":"string","description":"The refresh token received from previous access token requests. This is used for the refresh_token grant type."}},"required":["grant_type","client_id","refresh_token"],"description":"The Refresh Token request for a token for native apps.","title":"nativeTokenRequestWithRefreshToken"},"OAuth_post-oauth-refresh-token_Request":{"oneOf":[{"$ref":"#/components/schemas/webTokenRequestWithCode"},{"$ref":"#/components/schemas/webTokenRequestWithRefreshToken"},{"$ref":"#/components/schemas/nativeTokenRequestWithCode"},{"$ref":"#/components/schemas/nativeTokenRequestWithRefreshToken"}],"title":"OAuth_post-oauth-refresh-token_Request"},"TokenResponseTokenType":{"type":"string","enum":["Bearer"],"description":"The token type (currently this is always \"Bearer\")","title":"TokenResponseTokenType"},"tokenResponse":{"type":"object","properties":{"token_type":{"$ref":"#/components/schemas/TokenResponseTokenType","description":"The token type (currently this is always \"Bearer\")"},"access_token":{"type":"string","description":"The access token provided in the response"},"refresh_token":{"type":"string","description":"The refresh token provided in the response"},"scope":{"type":"string","description":"The scope of the access request"},"created_at":{"type":"number","format":"double","description":"The UNIX timestamp in seconds when the event was created"},"expires_in":{"type":"number","format":"double","description":"The number of seconds until the access token expires"},"owner":{"type":"string","format":"uri","description":"A link to the resource that owns the token (currently, this is always a user)"},"organization":{"type":"string","format":"uri","description":"A link to the owner's current organization"}},"required":["token_type","access_token","refresh_token","created_at","expires_in","owner","organization"],"description":"OAuth token response","title":"tokenResponse"},"OauthTokenPostResponsesContentApplicationJsonSchemaError":{"type":"string","enum":["temporarily_unavailable"],"description":"Error code indicating the service is temporarily unavailable due to rate limiting","title":"OauthTokenPostResponsesContentApplicationJsonSchemaError"},"Post-oauth-refresh-tokenRequestBadRequestError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/OauthTokenPostResponsesContentApplicationJsonSchemaError","description":"Error code"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"title":"Post-oauth-refresh-tokenRequestBadRequestError"},"ErrorResponseError":{"type":"string","enum":["invalid_client","unauthorized_client"],"description":"Error code","title":"ErrorResponseError"},"errorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorResponseError","description":"Error code"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"description":"OAuth error response","title":"errorResponse"},"Post-oauth-refresh-tokenRequestTooManyRequestsError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/OauthTokenPostResponsesContentApplicationJsonSchemaError","description":"Error code indicating the service is temporarily unavailable due to rate limiting"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"description":"Rate limiting error response","title":"Post-oauth-refresh-tokenRequestTooManyRequestsError"},"OauthAuthorizeGetParametersResponseType":{"type":"string","enum":["code"],"title":"OauthAuthorizeGetParametersResponseType"},"OAuth_get-oauth-authorize_Response_200":{"type":"object","properties":{},"description":"Empty response body","title":"OAuth_get-oauth-authorize_Response_200"},"OAuth_post-oauth-introspect_Response_200":{"type":"object","properties":{"active":{"type":"boolean","description":"Boolean indicator of whether or not the presented token is currently active"},"scope":{"type":"string","description":"The scope of the access token"},"client_id":{"type":"string","description":"The ID provided by Calendly for the web application"},"token_type":{"type":"string","description":"The token type (currently this is always \"Bearer\")"},"exp":{"type":"number","format":"double","description":"The UNIX timestamp in seconds when the access-token will expire"},"iat":{"type":"number","format":"double","description":"The UNIX timestamp in seconds when the access-token was originally issued"},"owner":{"type":"string","format":"uri","description":"A link to the resource that owns the token (currently, this is always a user)"},"organization":{"type":"string","format":"uri","description":"A link to the owner's current organization"}},"required":["active"],"title":"OAuth_post-oauth-introspect_Response_200"},"OauthIntrospectPostResponsesContentApplicationJsonSchemaError":{"type":"string","enum":["invalid_request"],"description":"Error code","title":"OauthIntrospectPostResponsesContentApplicationJsonSchemaError"},"Post-oauth-introspectRequestBadRequestError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/OauthIntrospectPostResponsesContentApplicationJsonSchemaError","description":"Error code"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"title":"Post-oauth-introspectRequestBadRequestError"},"OAuth_post-oauth-revoke_Response_200":{"type":"object","properties":{},"title":"OAuth_post-oauth-revoke_Response_200"},"OauthRevokePostResponsesContentApplicationJsonSchemaError":{"type":"string","enum":["invalid_request"],"description":"Error code","title":"OauthRevokePostResponsesContentApplicationJsonSchemaError"},"Post-oauth-revokeRequestBadRequestError":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/OauthRevokePostResponsesContentApplicationJsonSchemaError","description":"Error code"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"title":"Post-oauth-revokeRequestBadRequestError"},"Post-oauth-revokeRequestForbiddenError":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"error_description":{"type":"string","description":"Error description"}},"required":["error","error_description"],"title":"Post-oauth-revokeRequestForbiddenError"}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Use `client_id` for username and `client_secret` for password."}}}}