---
title: "ObtainToken"
method: POST
path: "/oauth2/token"
tags: ["OAuth"]
---

# ObtainToken

`POST /oauth2/token`

Returns an OAuth access token.

The endpoint supports distinct methods of obtaining OAuth access tokens.
Applications specify a method by adding the `grant_type` parameter
in the request and also provide relevant information.

__Note:__ Regardless of the method application specified,
the endpoint always returns two items; an OAuth access token and
a refresh token in the response.

__OAuth tokens should only live on secure servers. Application clients
should never interact directly with OAuth tokens__.

## Request body

- ObtainTokenRequest
  - `client_id` string, required — The Square-issued ID of your application, available from the [developer dashboard](https://developer.squareup.com/apps).
  - `client_secret` string, required — The Square-issued application secret for your application, available from the [developer dashboard](https://developer.squareup.com/apps).
  - `code` string — The authorization code to exchange. This is required if `grant_type` is set to `authorization_code`, to indicate that the application wants to exchange an authorization code for an OAuth access token.
  - `grant_type` string, required — Specifies the method to request an OAuth access token. Valid values are: `authorization_code`, `refresh_token`, and `migration_token`
  - `migration_token` string — Legacy OAuth access token obtained using a Connect API version prior to 2019-03-13. This parameter is required if `grant_type` is set to `migration_token` to indicate that the application wants to get a replacement OAuth access token. The response also returns a refresh token. For more information, see [Migrate to Using Refresh Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).
  - `redirect_uri` string — The redirect URL assigned in the [developer dashboard](https://developer.squareup.com/apps).
  - `refresh_token` string — A valid refresh token for generating a new OAuth access token. A valid refresh token is required if `grant_type` is set to `refresh_token` , to indicate the application wants a replacement for an expired OAuth access token.
  - `scopes` string[] — A JSON list of strings representing the permissions the application is requesting. For example: "`["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]`" The access token returned in the response is granted the permissions that comprise the intersection between the requested list of permissions, and those that belong to the provided refresh token.
  - `short_lived` boolean — A boolean indicating a request for a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.

## Response `200`

Success

- ObtainTokenResponse
  - `access_token` string — A valid OAuth access token. OAuth access tokens are 64 bytes long. Provide the access token in a header with every request to Connect API endpoints. See [OAuth API: Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough) for more information.
  - `expires_at` string — The date when access_token expires, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
  - `id_token` string — Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request.
  - `merchant_id` string — The ID of the authorizing merchant's business.
  - `plan_id` string — __LEGACY FIELD__. The ID of the subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.
  - `refresh_token` string — A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see [OAuth access token management](https://developer.squareup.com/docs/oauth-api/how-it-works#oauth-access-token-management).
  - `short_lived` boolean — A boolean indicating the access token is a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.
  - `subscription_id` string — __LEGACY FIELD__. The ID of a subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.
  - `token_type` string — This value is always _bearer_.

---

[API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)