### Revoke Access Token via cURL Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/revoke-tokens Example command to invalidate a user's access token. ```bash curl -v POST "https://appleid.apple.com/auth/oauth2/v2/revoke" \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'client_id=CLIENT_ID' \ -d 'client_secret=CLIENT_SECRET' \ -d 'token=ACCESS_TOKEN' \ -d 'token_type_hint=access_token' ``` -------------------------------- ### Fetch Apple's Public Key Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/fetch-apple%27s-public-key-for-verifying-token-signature Use this GET request to retrieve Apple's public key. The response contains the JWKSet.Keys object with the necessary public key for signature verification. ```HTTP GET https://appleid.apple.com/auth/oauth2/v2/keys ``` -------------------------------- ### Authorization Code Validation Response Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/generate-and-validate-tokens This is an example of a successful response after validating an authorization code. It includes access, refresh, and identity tokens. ```json { "access_token": "adg61...670r9", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rca7...lABoQ", "id_token": "eyJra...96sZg" } ``` -------------------------------- ### Revoke Refresh Token via cURL Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/revoke-tokens Example command to invalidate a user's refresh token. ```bash curl -v POST "https://appleid.apple.com/auth/oauth2/v2/revoke" \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'client_id=CLIENT_ID' \ -d 'client_secret=CLIENT_SECRET' \ -d 'token=REFRESH_TOKEN' \ -d 'token_type_hint=refresh_token' ``` -------------------------------- ### Refresh Token Validation Response Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/generate-and-validate-tokens This is an example of a successful response after validating a refresh token. It provides an access token and an identity token. ```json { "access_token": "beg510...670r9", "token_type": "Bearer", "expires_in": 3600, "id_token": "eyJra...96sZg" } ``` -------------------------------- ### GET https://appleid.apple.com/auth/oauth2/v2/keys Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/fetch-apple%27s-public-key-for-verifying-token-signature Retrieve the public key associated with the cryptographic identity Apple uses to sign the token. ```APIDOC ## GET https://appleid.apple.com/auth/oauth2/v2/keys ### Description Retrieve the public key associated with the cryptographic identity Apple uses to sign the token. ### Method GET ### Endpoint https://appleid.apple.com/auth/oauth2/v2/keys ### Response #### Success Response (200) - **JWKSet.Keys** (object) - Contains Apple's public key. #### Response Example { "keys": [ { "kty": "RSA", "kid": "...", "use": "sig", "alg": "RS256", "n": "...", "e": "..." } ] } ``` -------------------------------- ### Using and Revoking Tokens Source: https://developer.apple.com/documentation/AccountOrganizationalDataSharing This section explains how to request user authorization, use obtained tokens, and revoke them when necessary. ```APIDOC ## Using and Revoking Tokens This section outlines the processes for requesting user authorization, managing tokens, and revoking access. ### Request an Authorization Request a user authorization to Account & Organizational Data Sharing apps and web services. ### Token Revocation Invalidate the tokens and associated user authorizations for someone when they are no longer associated with your app. ``` -------------------------------- ### Generating Tokens Source: https://developer.apple.com/documentation/AccountOrganizationalDataSharing This section covers the process of generating and validating tokens required for accessing Apple services. ```APIDOC ## Generating Tokens This section details the procedures for creating and validating tokens necessary for authenticating with Apple services. ### Creating a Client Secret Generate a signed token to identify your client application. #### Fetch Apple's Public Key for Verifying Token Signature Retrieve the public key associated with the cryptographic identity Apple uses to sign the token. #### Generate and Validate Tokens Validate an authorization grant code delivered to your app to obtain tokens, or validate an existing refresh token. ``` -------------------------------- ### JWT Header for Client Secret Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret Use 'ES256' for the algorithm and a 10-character key identifier for 'kid'. ```json { "alg": "ES256", "kid": "ABC123DEFG" } ``` -------------------------------- ### JWKSet.Keys Object Definition Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/jwkset/jwkset.keys Defines the structure and properties of a JWKSet.Keys object, which represents a single JSON Web Key. ```APIDOC ## JWKSet.Keys An object that defines a single JSON Web Key. ### Properties - **alg** (string) - The encryption algorithm used to encrypt the token. - **e** (string) - The exponent value for the RSA public key. - **kid** (string) - A 10-character identifier key, obtained from your developer account. - **kty** (string) - The key type parameter setting. Use the value `RSA`. - **n** (string) - The modulus value for the RSA public key. - **use** (string) - The intended use for the public key. ``` -------------------------------- ### POST /auth/oauth2/v2/token Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/generate-and-validate-tokens Validates an authorization grant code or an existing refresh token to obtain authentication tokens. ```APIDOC ## POST https://appleid.apple.com/auth/oauth2/v2/token ### Description Validates an authorization grant code delivered to your app to obtain tokens, or validates an existing refresh token. ### Method POST ### Endpoint https://appleid.apple.com/auth/oauth2/v2/token ### Parameters #### Request Body - **client_id** (string) - Required - The identifier (App ID or Services ID) for your app. - **client_secret** (string) - Required - A secret JWT, generated by the developer, that uses the Account and Organizational Data Sharing private key. - **code** (string) - Optional - The authorization code received in an authorization response. - **grant_type** (string) - Required - The grant type. Use 'authorization_code' for code validation or 'refresh_token' for refresh token validation. - **redirect_uri** (string) - Optional - The destination URI provided in the authorization request. - **refresh_token** (string) - Optional - The refresh token received from the validation server. ### Request Example curl -v POST "https://appleid.apple.com/auth/oauth2/v2/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' ### Response #### Success Response (200) - **access_token** (string) - The access token. - **token_type** (string) - The type of token (e.g., Bearer). - **expires_in** (integer) - Expiration time in seconds. - **refresh_token** (string) - The refresh token (if applicable). - **id_token** (string) - The identity token. #### Response Example { "access_token": "adg61...670r9", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rca7...lABoQ", "id_token": "eyJra...96sZg" } ``` -------------------------------- ### Request an Authorization Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/request-an-authorization Request a user authorization to Account & Organizational Data Sharing apps and web services. This endpoint is available for AccountOrganizationalDataSharing 1.0+. ```APIDOC ## GET https://appleid.apple.com/auth/oauth2/v2/authorize ### Description Request a user authorization to Account & Organizational Data Sharing apps and web services. ### Method GET ### Endpoint https://appleid.apple.com/auth/oauth2/v2/authorize ### Query Parameters - **client_id** (string) - Required - The identifier (App ID or Services ID) for your app. To prevent exposing sensitive data to the end user, don’t include your Team ID in the identifier. - **nonce** (string) - Optional - A unique, single-use string that your app provides to associate a client session with the user’s identity token. This value also prevents replay attacks, and correlates the initial authentication request to the identity token provided in the authorization response. - **redirect_uri** (string) - Required - The destination URI associated with your app that the authorization redirects. The URI must use the HTTPS protocol, include a domain name, can’t be an IP address or `localhost`, and must not contain a fragment identifier (`#`). - **response_mode** (string) - Optional - Specifies how the authorization response should be delivered. - **response_type** (string) - Required - The type of response requested. Use the value `code`. - **scope** (string) - Required - The amount of personal information your app or web service requests from Apple’s servers. Valid values are `edu.users.read` and `edu.classes.read`. You can request one, both, or none. Use space separation and percent-encoding for multiple scopes; for example, `"scope=edu.users.read%20edu.classes.read"`. - **state** (string) - Optional - An arbitrary string that your app provides to represent the current state of the authorization request. This value mitigates cross-site request forgery attacks by comparing against the state value contained in the authorization response. ### Response Codes - **200 OK** - The request was successful. Content-Type: application/json - **404 Not Found** - Resource not found. Content-Type: application/json ``` -------------------------------- ### JWKSet Object Definition Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/jwkset Defines the structure of the JWKSet object and its associated keys. ```APIDOC ## JWKSet ### Description A set of JSON web keys used for Account & Organizational Data Sharing. ### Properties - **keys** (JWKSet.Keys[]) - A collection of JSON Web Keys. ### Related Objects - **TokenResponse** - The response token object returned on a successful request. - **ErrorResponse** - The error object returned after an unsuccessful request. ``` -------------------------------- ### Common Objects Source: https://developer.apple.com/documentation/AccountOrganizationalDataSharing Definitions for common objects used within the Account & Organizational Data Sharing API. ```APIDOC ## Common Objects This section defines the common data structures used throughout the Account & Organizational Data Sharing API. ### Object JWKSet A set of JSON web keys. ### Object TokenResponse The response token object returned on a successful request. ### Object ErrorResponse The error object returned after an unsuccessful request. ``` -------------------------------- ### TokenResponse Object Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/tokenresponse The TokenResponse object is returned on a successful request and contains various tokens related to data access and user identity. ```APIDOC ## TokenResponse Object ### Description The response token object returned on a successful request for Account & Organizational Data Sharing. ### Properties - **access_token** (string) - A token used to access allowed data. - **expires_in** (number) - The amount of time, in seconds, before the access token expires. - **id_token** (string) - A JWT that contains the user’s identity information. - **refresh_token** (string) - The refresh token used to regenerate new access tokens when validating an authorization code. Store this token securely on your server. The refresh token isn’t returned when validating an existing refresh token. - **token_type** (string) - The type of access token, which is always `bearer`. ### See Also - `object JWKSet` - `object ErrorResponse` ``` -------------------------------- ### Account & Organizational Data Sharing API Source: https://developer.apple.com/documentation/accountorganizationaldatasharing This section outlines the core functionalities of the Account & Organizational Data Sharing API, including token generation, management, and error handling. ```APIDOC ## Account & Organizational Data Sharing API ### Description Provides users with the ability to authorize your apps and websites to access information about them on Apple REST services, like Roster API, using OAuth 2.0. ### Topics #### Generating Tokens ##### Creating a Client Secret Generate a signed token to identify your client application. ##### Fetch Apple's Public Key Retrieve the public key associated with the cryptographic identity Apple uses to sign the token. ##### Generate and Validate Tokens Validate an authorization grant code delivered to your app to obtain tokens, or validate an existing refresh token. #### Using and Revoking Tokens ##### Request an Authorization Request a user authorization to Account & Organizational Data Sharing apps and web services. ##### Token Revocation Invalidate the tokens and associated user authorizations for someone when they are no longer associated with your app. ### Common Objects #### JWKSet A set of JSON web keys. #### TokenResponse The response token object returned on a successful request. #### ErrorResponse The error object returned after an unsuccessful request. ``` -------------------------------- ### Validate Authorization Grant Code Request Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/generate-and-validate-tokens Use this curl command to validate an authorization grant code. Ensure all parameters are correctly formatted and included. ```curl curl -v POST "https://appleid.apple.com/auth/oauth2/v2/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' ``` -------------------------------- ### JWT Payload for Client Secret Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret Include issuer (Team ID), issue time, expiration time, audience ('https://appleid.apple.com'), and subject (App ID or Services ID). ```json { "iss": "DEF123GHIJ", "iat": 1437179036, "exp": 1493298100, "aud": "https://appleid.apple.com", "sub": "com.mytest.app" } ``` -------------------------------- ### Validate Refresh Token Request Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/generate-and-validate-tokens Use this curl command to validate an existing refresh token. This is useful for verifying user sessions or obtaining new access tokens. ```curl curl -v POST "https://appleid.apple.com/auth/oauth2/v2/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' ``` -------------------------------- ### ErrorResponse Object Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/errorresponse The ErrorResponse object is returned when an API request fails. It contains a single property, 'error', which specifies the reason for the failure. ```APIDOC ## ErrorResponse Object ### Description The error object returned after an unsuccessful request. ### Properties - **error** (string) - Required - A string that describes the reason for the unsuccessful request. The string is one of the allowed values, listed below. Possible Values: `invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope` ### Overview of Error Values - `invalid_request`: A malformed request, typically because it’s missing a parameter, contains an unsupported parameter, includes multiple credentials, or uses more than one mechanism for authenticating the client. - `invalid_client`: The client authentication failed, typically due to a mismatched or invalid client identifier, invalid client secret (expired token, malformed claims, or invalid signature), or mismatched or invalid redirect URI. - `invalid_grant`: The authorization grant or refresh token is invalid, typically due to a mismatched or invalid client identifier, invalid code (expired or previously used authorization code), or invalid refresh token. - `unauthorized_client`: The client isn’t authorized to use this authorization grant type. - `unsupported_grant_type`: The authenticated client isn’t authorized to use this grant type. - `invalid_scope`: The requested scope is invalid. ### Request Example ```json { "error": "invalid_request" } ``` ### Response Example ```json { "error": "invalid_client" } ``` ``` -------------------------------- ### Revoke Token Endpoint URL Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/revoke-tokens The base URL for the token revocation POST request. ```http POST https://appleid.apple.com/auth/oauth2/v2/revoke ``` -------------------------------- ### POST /auth/oauth2/v2/revoke Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/revoke-tokens Invalidates a user's refresh token or access token to revoke authorization. ```APIDOC ## POST https://appleid.apple.com/auth/oauth2/v2/revoke ### Description Invalidate the tokens and associated user authorizations for someone when they are no longer associated with your app. ### Method POST ### Endpoint https://appleid.apple.com/auth/oauth2/v2/revoke ### Parameters #### Request Body - **client_id** (string) - Required - The identifier (App ID or Services ID) for your app. - **client_secret** (string) - Required - A secret JWT that uses the Account and Organizational Data Sharing private key. - **token** (string) - Required - The user refresh token or access token intended to be revoked. - **token_type_hint** (string) - Optional - A hint about the type of the token submitted (refresh_token or access_token). ### Response #### Success Response (200) - **Status** - The request was successful; the provided token has been revoked successfully or was previously invalid. #### Error Response (400) - **ErrorResponse** - The server was unable to process the request. ``` -------------------------------- ### JWT Client Secret Structure Source: https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret The structure of the JWT header and payload required to authenticate requests to the Account and Organizational Data Sharing REST API. ```APIDOC ## JWT Client Secret Structure ### Description Defines the required fields for the JWT header and payload used to generate a client secret for API authorization. ### Header Fields - **alg** (string) - Required - The algorithm used to sign the token; must be 'ES256'. - **kid** (string) - Required - The 10-character key identifier for the private key. ### Payload Claims - **iss** (string) - Required - The 10-character Team ID of the developer account. - **iat** (integer) - Required - The time the token was generated (seconds since epoch). - **exp** (integer) - Required - The expiration time (max 15,777,000 seconds from issuance). - **aud** (string) - Required - The audience; must be 'https://appleid.apple.com'. - **sub** (string) - Required - The App ID or Services ID (client_id). ### Request Example { "alg": "ES256", "kid": "ABC123DEFG" } { "iss": "DEF123GHIJ", "iat": 1437179036, "exp": 1493298100, "aud": "https://appleid.apple.com", "sub": "com.mytest.app" } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.