--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Get Access Token v3 Either: 1) Exchanges an authorization_code for an access_token, or 2) Exchanges a refresh_token for an access_token. When exchanging a refresh_token for an access_token, also invalidates existing refresh_token and generates a new refresh_token. See [Refresh Tokens](https://docs.developer.yelp.com/docs/refresh-tokens) for how this works > 📘 > > This endpoint is part of the OAuth Authorization flow, visit [OAuth Authorization](https://docs.developer.yelp.com/docs/oauth-authorization) to learn more. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "OAuth Authorization v2", "version": "1.0" }, "servers": [ { "url": "https://api.yelp.com/oauth2" } ], "components": { "schemas": { "client_id": { "type": "string", "description": "ID assigned by Yelp for the third-party system that will make user-authorized requests to Yelp." }, "client_secret": { "type": "string", "description": "Client secret assigned by Yelp for the third-party system that will make user-authorized requests to Yelp.", "maxLength": 64, "minLength": 64 }, "token": { "type": "string", "maxLength": 128, "minLength": 128, "pattern": "[A-Za-z0-9+/=]+" }, "TokenRequestBase": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/client_id" }, "client_secret": { "$ref": "#/components/schemas/client_secret" }, "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ], "description": "Grant type, as per specified in OAuth2 RFC." } }, "required": [ "client_id", "client_secret", "grant_type" ] }, "TokenAuthorizationCodeRequest": { "title": "Access Token Request", "type": "object", "description": "Access Token Request as per https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3", "allOf": [ { "$ref": "#/components/schemas/TokenRequestBase" }, { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Value MUST be set to \"authorization_code\".", "enum": [ "authorization_code" ] }, "code": { "type": "string", "description": "Authorization code that is sent back to the redirect uri after a biz user authorized the client's oauth client." }, "redirect_uri": { "type": "string", "description": "REQUIRED, if the \"redirect_uri\" parameter was included in the authorization request and their values MUST be identical." }, "code_verifier": { "type": "string", "description": "PKCE code verifier (RFC 7636). The original random string used to generate the\ncode_challenge sent in the authorization request. Required when the authorization\nrequest included a code_challenge. Must be between 43 and 128 characters,\nusing [A-Z] / [a-z] / [0-9] / \"-\" / \".\" / \"_\" / \"~\".\n", "minLength": 43, "maxLength": 128, "pattern": "^[A-Za-z0-9\\-._~]+$" }, "code_challenge_method": { "type": "string", "description": "The method used to derive the code_challenge from the code_verifier.\nOnly S256 is supported.\n", "enum": [ "S256" ] } }, "required": [ "authorization_code", "code" ] } ] }, "TokenRefreshTokenRequest": { "title": "Refresh Access Token Request", "type": "object", "description": "Refresh Access Token Request as per https://www.rfc-editor.org/rfc/rfc6749#section-6", "allOf": [ { "$ref": "#/components/schemas/TokenRequestBase" }, { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Value MUST be set to \"refresh_token\".", "enum": [ "refresh_token" ] }, "refresh_token": { "type": "string", "description": "The refresh token issued to the client." }, "scope": { "type": "string", "description": "Clients can specify a smaller subset of scopes, if desired. However, they cannot\n specify any scopes that were not previously defined. If not specified, the original scope is returned.\n" } }, "required": [ "authorization_code", "refresh_token" ] } ] }, "TokenRefreshTokenResponse": { "title": "Response when calling this endpoint using a refresh token.", "type": "object", "properties": { "access_token": { "$ref": "#/components/schemas/token", "description": "Token issued by the authorization server. Tokens will be valid for 7 days." }, "expires_in": { "description": "Seconds until token expires.", "type": "integer" }, "expires_on": { "description": "The expiration time of the access token in ISO8601 format.", "type": "string", "format": "date-time" }, "token_type": { "description": "The type of token issued. Default to ‘Bearer’", "type": "string" } }, "required": [ "access_token", "expires_in", "expires_on", "token_type" ] }, "TokenAuthorizationCodeResponse": { "title": "Response when calling this endpoint using an authorization code.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TokenRefreshTokenResponse" }, { "type": "object", "properties": { "refresh_token": { "$ref": "#/components/schemas/token", "description": "Refresh token that can be used to refresh the access token. Refresh tokens expire after 365 days." }, "refresh_token_expires_in": { "description": "Seconds until refresh token expires.", "type": "integer" }, "refresh_token_expires_on": { "description": "The expiration time of the refresh token in ISO8601 format.", "type": "string", "format": "date-time" }, "scopes": { "description": "Space separated scope values for the scope the business owner authorized the partner's application for.", "type": "string" } }, "required": [ "refresh_token", "refresh_token_expires_in", "refresh_token_expires_on", "scopes" ] } ] }, "Error400": { "description": "Bad Request", "content": { "application/json": { "examples": { "INVALID_REQUEST": { "value": { "error": { "code": "INVALID_REQUEST", "description": "'refresh_token' parameter not specified" } } }, "INVALID_GRANT": { "value": { "error": { "code": "INVALID_GRANT", "description": "The grant type you provided is invalid, expired or revoked." } } }, "UNSUPPORTED_GRANT_TYPE": { "value": { "error": { "code": "UNSUPPORTED_GRANT_TYPE", "description": "The authenticated client is not authorized to use this authorization grant type." } } }, "BAD_CLIENT_ID_OR_SECRET": { "value": { "error": { "code": "BAD_CLIENT_ID_OR_SECRET", "description": "Invalid combination of client_id and client_secret." } } }, "UNAUTHORIZED_CLIENT": { "value": { "error": { "code": "UNAUTHORIZED_CLIENT", "description": "Specified client is not authorized." } } } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The error code." }, "description": { "type": "string", "description": "The description of the error." } } } } } } } } }, "examples": { "TokenAuthorizationCodeResponse": { "value": { "access_token": "AfzWrtxA8kNHtswWExRUsRGKq43YuLI37y8ko6JDOxWZvGIX8ERwlOyUADmf5V6kaAdfIKafmmCjf4s8JGvkUugqBhoyO1WImlHg5i7g5QHRl07vG95rpTYMtIo3uo5H", "expires_in": 604799, "expires_on": "2022-11-10T12:29:56+00:00", "token_type": "Bearer", "refresh_token": "sMJDp1qSPQuZ1rAJlJToX2wLFu1S6HRPFC9UlCkN8VP3wh4qqN2Ba4J1Jc5NcVixkw9CA4TGZ7zEKIq2mTyWHojzVcgnYLH2JVIhKGAfko9Uc1ANfvFtItpcgalKAP2W", "refresh_token_expires_in": 31535999, "refresh_token_expires_on": "2023-11-03T12:29:56+00:00", "scope": "leads r2r" } }, "TokenRefreshTokenResponse": { "value": { "access_token": "AfzWrtxA8kNHtswWExRUsRGKq43YuLI37y8ko6JDOxWZvGIX8ERwlOyUADmf5V6kaAdfIKafmmCjf4s8JGvkUugqBhoyO1WImlHg5i7g5QHRl07vG95rpTYMtIo3uo5H", "expires_in": 604799, "expires_on": "2022-11-10T12:29:56+00:00", "token_type": "Bearer" } } } }, "paths": { "/token/v3": { "post": { "tags": [ "OAuth Authorization v3" ], "summary": "Get Access Token v3", "operationId": "oauth2_token_v3", "description": "Either:\n 1) Exchanges an authorization_code for an access_token, or\n 2) Exchanges a refresh_token for an access_token.\nWhen exchanging a refresh_token for an access_token, also invalidates existing refresh_token and generates a new refresh_token.\nSee [Refresh Tokens](https://docs.developer.yelp.com/docs/refresh-tokens) for how this works\n", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TokenAuthorizationCodeRequest" }, { "$ref": "#/components/schemas/TokenRefreshTokenRequest" } ] } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TokenAuthorizationCodeResponse" }, { "$ref": "#/components/schemas/TokenRefreshTokenResponse" } ] }, "examples": { "Authorization Code Example": { "$ref": "#/components/examples/TokenAuthorizationCodeResponse" }, "Refresh Token Example": { "$ref": "#/components/examples/TokenRefreshTokenResponse" } } } } }, "400": { "$ref": "#/components/schemas/Error400" }, "429": { "description": "You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "error": { "code": "TOO_MANY_REQUESTS_PER_SECOND", "description": "You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries." } } } }, "schema": { "$ref": "#/components/schemas/Error400/content/application~1json/schema" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "examples": { "Internal Server Error": { "value": { "error": { "code": "INTERNAL_ERROR", "description": "Something went wrong internally, please try again later." } } } }, "schema": { "$ref": "#/components/schemas/Error400/content/application~1json/schema" } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 99, "1": 99, "2": 204, "3": 161, "4": 63, "5": 102, "6": 197, "7": 2, "8": 143, "9": 171, "10": 31, "11": 103 } } } ```