Start Apple OAuth flow

GET
https://test.stytch.com/v1/public/oauth/apple/start

A client-side endpoint (can only be queried from the user's browser) that starts the Apple OAuth flow. This endpoint generates the Apple OAuth URL with all of the required fields and redirects a user to that URL. From there, the user signs into their Apple Account before getting redirected back to Stytch. After verifying the request, Stytch immediately redirects the user back to the login_redirect_url or signup_redirect_url URLs provided.

Scopes

By default our Apple OAuth integration includes open_id, email, and profile scopes. You may add any additional Apple API scopes (see here for a complete list) as a space separated list in the custom_scopes query parameter of /oauth/apple/start.

Additional provider parameters

Any parameters that should be forwarded to the OAuth provider can be passed as query parameters with the provider_ prefix. For example, some OAuth providers support a login_hint parameter that allows you to pre-populate the OAuth login flow with a suggested email address. To specify the login_hint parameter in your OAuth request, you'd include provider_login_hint=exampleHint as a query parameter. We recommend consulting each OAuth provider's documentation for a list of supported parameters.

Next steps

Once the user successfully authenticates with Apple, they'll be redirected to the redirect URL that you provided at the start of the OAuth flow with a Stytch OAuth token. Collect the token from the URL query parameters, and call Authenticate OAuth token to complete authentication.

Query parameters

public_token* string

The public token from the Stytch Dashboard is safe to embed client side. The public token authenticates the request instead of the project ID and secret since this endpoint is called client side instead of from the backend server.

login_redirect_url string

The URL Stytch redirects to after the OAuth flow is completed for a user that already exists. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

signup_redirect_url string

The URL Stytch redirects to after the OAuth flow is completed for a user that does not yet exist. This URL should be a route in your application which will run oauth.authenticate (see below) and finish the login.

The URL must be configured as a Login URL in the Redirect URL page. If the field is not specified, the default Login URL will be used.

custom_scopes string

Include a space separated list of custom scopes that you'd like to include. Note that this list must be URL encoded, i.e. the spaces must be expressed as %20.

provider_[parameter] string

Any parameters that should be forwarded to the OAuth provider can be passed as query parameters with the provider_ prefix. For example, some OAuth providers support a login_hint parameter that allows you to pre-populate the OAuth login flow with a suggested email address. To specify the login_hint parameter in your OAuth request, you'd include provider_login_hint=exampleHint as a query parameter. We recommend consulting each OAuth provider's documentation for a list of supported parameters.

code_challenge string

A base64url encoded SHA256 hash of a one time secret used to validate that the request starts and ends on the same device.

oauth_attach_token string

A single-use token for connecting the Stytch User selection from an OAuth Attach request to the corresponding OAuth Start request.

Response fields

status_code int

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.

request_id string

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.

redirect_url RedirectURL

The RedirectURL that was created

// Not applicable since this endpoint is only meant to be queried on the client's browser
RESPONSE 302
{
    "status_code": 302,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "redirect_url": "https://appleid.apple.com/auth/authorize?client_id=example-client-id&redirect_uri=https%3A%2F%2Fstytch.com%2Fv1%2Foauth%2Foauth-callback-test-d868b16b-3ecd-49ac-7fc6-e3d1051c5d65&response_type=code&response_mode=form_post&scope=name%20email&state=example-state",
}
RESPONSE 401
{
  "status_code": 401,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "unable_to_auth_oauth_token",
  "error_message": "OAuth request could not be authenticated.",
  "error_url": "https://stytch.com/docs/api/errors/401"
}
RESPONSE 404
{
  "status_code": 404,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "oauth_config_not_found",
  "error_message": "OAuth provider isn't configured.",
  "error_url": "https://stytch.com/docs/api/errors/404"
}
RESPONSE 429
{
  "status_code": 429,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "too_many_requests",
  "error_message": "Too many requests have been made.",
  "error_url": "https://stytch.com/docs/api/errors/429"
}
RESPONSE 500
{
  "status_code": 500,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "internal_server_error",
  "error_message": "Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.",
  "error_url": "https://stytch.com/docs/api/errors/500"
}

Common Error Types