Web Service Endpoint

Generate and Validate Tokens

Validate an authorization grant code delivered to your app to obtain tokens, or validate an existing refresh token.

URL

POST https://appleid.apple.com/auth/token

HTTP Body

form-data

The list of input parameters required for the server to validate the authorization code or refresh token.

Parts

client_id
string
(Required)

The identifier (App ID or Services ID) for your app. The identifier must not include your Team ID, to help mitigate sensitive data exposure to the end user. This parameter is required for both authorization code and refresh token validation requests.

client_secret
string
(Required)

A secret JSON Web Token, generated by the developer, that uses the Sign in with Apple private key associated with your developer account. This parameter is required for both authorization code and refresh token validation requests.

code
string

The authorization code received in an authorization response sent to your app. The code is single-use only and valid for five minutes. This parameter is required for authorization code validation requests.

grant_type
string
(Required)

The grant type determines how the client app interacts with the validation server. This parameter is required for both authorization code and refresh token validation requests. For authorization code validation, use authorization_code. For refresh token validation requests, use refresh_token.

refresh_token
string

The refresh token received from the validation server during a authorization request. This parameter is required for refresh token validation requests.

redirect_uri
string

The destination URI provided in the authorization request when authorizing a user with your app, if applicable. The URI must use the HTTPS protocol, include a domain name, and cannot contain an IP address or localhost. This parameter is required for authorization code validation requests.

Response Codes

OK

The request was successful.

400 Bad Request
Bad Request

The server was unable to process the request.

Discussion

The validation server returns a TokenResponse object in the response body of a successful validation request. Use this endpoint to either authorize a user by validating the authorization code received by your app, or by validating an existing refresh token to verify a user session or obtain access tokens.

Validate the Authorization Grant Code

When the developer attempts an authorization request to the validation server, the following form data parameters are required:

  • client_id

  • client_secret

  • code

  • grant_type

  • redirect_uri

The following is an example authorization validation request URL via cURL:

curl -v POST "https://appleid.apple.com/auth/token" \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id=CLIENT_ID' \
-d 'client_secret=CLIENT_SECRET' \
-d 'code=CODE' \
-d 'grant_type=authorization_code' \
-d 'redirect_uri=REDIRECT_URI'

After the authorization code has been validated, the endpoint returns the identity token, an access token, and a refresh token. Use the refresh token to:

  • Verify the user session from the server

  • Obtain access tokens

Validate an Existing Refresh Token

When the developer attempts a validation request, the following form data parameters are required:

  • client_id

  • client_secret

  • grant_type

  • refresh_token

The following is an example validation request URL via cURL:

curl -v POST "https://appleid.apple.com/auth/token" \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'client_id=CLIENT_ID' \
-d 'client_secret=CLIENT_SECRET' \
-d 'grant_type=refresh_token' \
-d 'refresh_token=REFRESH_TOKEN'

Creating the Client Secret

JSON Web Token (JWT) is an open-standard (RFC 7519) that defines a way to securely transmit information. Sign in with Apple requires JWTs to authorize each validation request. Create the token, then sign it with the private key you downloaded from Apple Developer.

To generate a signed JWT:

  1. Create the JWT header.

  2. Create the JWT payload.

  3. Sign the JWT.

To create a JWT, use the following fields and values in the JWT header:

Header

Description

alg

The algorithm used to sign the token. For Sign in with Apple, use ES256.

kid

A 10-character key identifier generated for the Sign in with Apple private key associated with your developer account.

The JWT payload contains information specific to the Sign in with Apple REST API and the client app, such as issuer, subject, and expiration time. Use the following claims in the payload:

Claim

Description

iss

The issuer registered claim identifies the principal that issued the client secret. Since the client secret was generated for your developer team, use your 10-character Team ID associated with your developer account.

iat

The issued at registered claim indicates the time at which you generated the client secret, in terms of the number of seconds since Epoch, in UTC.

exp

The expiration time registered claim identifies the time on or after which the client secret will expire. The value must not be greater than 15777000 (6 months in seconds) from the Current Unix Time on the server.

aud

The audience registered claim identifies the recipient for which the client secret is intended. Since the client secret is send to the validation server, use https://appleid.apple.com.

sub

The subject registered claim identifies the principal that is the subject of the client secret. Since this client secret is meant for your application, use the same value as client_id. The value is case-sensitive.

After creating the JWT, sign it using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve and the SHA-256 hash algorithm. A decoded client_secret JWT token has the following format:

{
    "alg": "ES256",
    "kid": "ABC123DEFG"
}
{
    "iss": "DEF123GHIJ",
    "iat": 1437179036,
    "exp": 1493298100,
    "aud": "https://appleid.apple.com",
    "sub": "com.mytest.app"
}

Regardless of the programming language you’re using with the Sign in with Apple REST API, there are a variety of open source libraries available online for creating and signing JWT tokens. See JWT.io for more information.