---
title: "Attach"
method: POST
path: "/v1/oauth/attach"
tags: ["Oauth"]
---

# Attach

`POST /v1/oauth/attach`

## Request

- Base URL: `https://api.stytch.com`
- URL: `https://api.stytch.com/v1/oauth/attach`
- Auth: HTTP basic

Generate an OAuth Attach Token to pre-associate an OAuth flow with an existing Stytch User. Pass the returned `oauth_attach_token` to the same provider's OAuth Start endpoint to treat this OAuth flow as a login for that user instead of a signup for a new user.

Exactly one of `user_id`, `session_token`, or `session_jwt` must be provided to identify the target Stytch User.

**Note**: This is an optional step in the OAuth flow. Stytch can often determine whether to associate a new OAuth login with an existing User based on verified information (such as an email address) from the identity provider. This endpoint is useful for cases where we can't, such as missing or unverified provider information.

See our [OAuth email address behavior](https://stytch.com/docs/guides/oauth/email-behavior) resource for additional information.

## Request body

- ApiOauthV1AttachRequest: Request type
  - `provider` string, required: The OAuth provider's name.
  - `user_id` string: The unique ID of a specific User. You may use an `external_id` here if one is set for the user.
  - `session_token` string: The `session_token` associated with a User's existing Session.
  - `session_jwt` string: The `session_jwt` associated with a User's existing Session.

## Response `200`

Successful response

- ApiOauthV1AttachResponse
  - `request_id` string, required: Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
  - `oauth_attach_token` string, required: A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.
  - `status_code` integer, required: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-03-07** `110f26a94e5b`: 1 info
  - endpoint added
- **2026-03-06** `9cab20b8eca7`: 1 breaking
  - api path removed without deprecation
- **2025-09-17** `8270cf3a3d4c`: 3 info
  - added the media type `application/json` for the response with the status `401`
  - added the media type `application/json` for the response with the status `500`
  - added the non-success response with the status `429`
- **2025-09-17** `864b9f438ac0`: 1 breaking
  - the `status_code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `200`

[Operation history](https://skmtc.dev/stytch/apis/stytch-api/changes/v1/oauth/attach/post.md)

---

[API](https://skmtc.dev/stytch/apis/stytch-api.md) - [All operations](https://skmtc.dev/stytch/apis/stytch-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stytch/apis/stytch-api/revisions/6d1ff7474803?raw)