--- title: "ObtainToken" method: POST path: "/oauth2/token" tags: ["OAuth"] --- # ObtainToken `POST /oauth2/token` Returns an OAuth access token and refresh token using the `authorization_code` or `refresh_token` grant type. When `grant_type` is `authorization_code`: - With the [code flow](https://developer.squareup.com/docs/oauth-api/overview#code-flow), provide `code`, `client_id`, and `client_secret`. - With the [PKCE flow](https://developer.squareup.com/docs/oauth-api/overview#pkce-flow), provide `code`, `client_id`, and `code_verifier`. When `grant_type` is `refresh_token`: - With the code flow, provide `refresh_token`, `client_id`, and `client_secret`. The response returns the same refresh token provided in the request. - With the PKCE flow, provide `refresh_token` and `client_id`. The response returns a new refresh token. You can use the `scopes` parameter to limit the set of permissions authorized by the access token. You can use the `short_lived` parameter to create an access token that expires in 24 hours. __Important:__ OAuth tokens should be encrypted and stored on a secure server. Application clients should never interact directly with OAuth tokens. ## Request body - ObtainTokenRequest — Represents an [ObtainToken](api-endpoint:OAuth-ObtainToken) request. - `client_id` string, required — The Square-issued ID of your application, which is available as the **Application ID** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow and PKCE flow for any grant type. - `client_secret` string, nullable — The secret key for your application, which is available as the **Application secret** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow for any grant type. Don't confuse your client secret with your personal access token. - `code` string, nullable — The authorization code to exchange for an OAuth access token. This is the `code` value that Square sent to your redirect URL in the authorization response. Required for the code flow and PKCE flow if `grant_type` is `authorization_code`. - `redirect_uri` string, nullable — The redirect URL for your application, which you registered as the **Redirect URL** on the **OAuth** page in the [Developer Console](https://developer.squareup.com/apps). Required for the code flow and PKCE flow if `grant_type` is `authorization_code` and you provided the `redirect_uri` parameter in your authorization URL. - `grant_type` string, required — The method used to obtain an OAuth access token. The request must include the credential that corresponds to the specified grant type. Valid values are: - `authorization_code` - Requires the `code` field. - `refresh_token` - Requires the `refresh_token` field. - `migration_token` - LEGACY for access tokens obtained using a Square API version prior to 2019-03-13. Requires the `migration_token` field. - `refresh_token` string, nullable — A valid refresh token used to generate a new OAuth access token. This is a refresh token that was returned in a previous `ObtainToken` response. Required for the code flow and PKCE flow if `grant_type` is `refresh_token`. - `migration_token` string, nullable — __LEGACY__ A valid access token (obtained using a Square API version prior to 2019-03-13) used to generate a new OAuth access token. Required if `grant_type` is `migration_token`. For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens). - `scopes` string[], nullable — The list of permissions that are explicitly requested for the access token. For example, ["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]. The returned access token is limited to the permissions that are the intersection of these requested permissions and those authorized by the provided `refresh_token`. Optional for the code flow and PKCE flow if `grant_type` is `refresh_token`. - `short_lived` boolean, nullable — Indicates whether the returned access token should expire in 24 hours. Optional for the code flow and PKCE flow for any grant type. The default value is `false`. - `code_verifier` string, nullable — The secret your application generated for the authorization request used to obtain the authorization code. This is the source of the `code_challenge` hash you provided in your authorization URL. Required for the PKCE flow if `grant_type` is `authorization_code`. - `use_jwt` boolean, nullable — Indicates whether to use a JWT (JSON Web Token) as the OAuth access token. When set to `true`, the OAuth flow returns a JWT to your application, used in the same way as a regular token. The default value is `false`. ## Response `200` Success - ObtainTokenResponse — Represents an [ObtainToken](api-endpoint:OAuth-ObtainToken) response. - `access_token` string — An OAuth access token used to authorize Square API requests on behalf of the seller. Include this token as a bearer token in the `Authorization` header of your API requests. OAuth access tokens expire in 30 days (except `short_lived` access tokens). You should call `ObtainToken` and provide the returned `refresh_token` to get a new access token well before the current one expires. For more information, see [OAuth API: Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough). - `token_type` string — The type of access token. This value is always `bearer`. - `expires_at` string — The timestamp of when the `access_token` expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. - `merchant_id` string — The ID of the authorizing [merchant](entity:Merchant) (seller), which represents a business. - `subscription_id` string — __LEGACY__ The ID of merchant's subscription. The ID is only present if the merchant signed up for a subscription plan during authorization. - `plan_id` string — __LEGACY__ The ID of the subscription plan the merchant signed up for. The ID is only present if the merchant signed up for a subscription plan during authorization. - `id_token` string — The OpenID token that belongs to this person. This token is only present if the `OPENID` scope is included in the authorization request. Deprecated at version 2021-09-15. Square doesn't support OpenID or other single sign-on (SSO) protocols on top of OAuth. - `refresh_token` string — A refresh token that can be used in an `ObtainToken` request to generate a new access token. With the code flow: - For the `authorization_code` grant type, the refresh token is multi-use and never expires. - For the `refresh_token` grant type, the response returns the same refresh token. With the PKCE flow: - For the `authorization_code` grant type, the refresh token is single-use and expires in 90 days. - For the `refresh_token` grant type, the refresh token is a new single-use refresh token that expires in 90 days. For more information, see [Refresh, Revoke, and Limit the Scope of OAuth Tokens](https://developer.squareup.com/docs/oauth-api/refresh-revoke-limit-scope). - `short_lived` boolean — Indicates whether the access_token is short lived. If `true`, the access token expires in 24 hours. If `false`, the access token expires in 30 days. - `errors` Error[] — Any errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `detail` string — A human-readable description of the error for debugging purposes. - `field` string — The name of the field provided in the original request (if any) that the error pertains to. - `refresh_token_expires_at` string — The timestamp of when the `refresh_token` expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. This field is only returned for the PKCE flow. --- [API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/versions/6a5164284e41/schema)