Wallet-as-a-ServiceAuthenticationApple

Apple Authentication

This guide walks you through setting up Apple Sign In as a custom authentication provider for your UTXOS application.

Custom authentication providers are available on Pro and Scale plans. The Base plan uses UTXOS-managed Apple credentials.

Prerequisites

⚠️

Apple Developer Program membership is required. The free Apple Developer account does not support Sign In with Apple for web applications.

Create an App ID

  1. Navigate to the Apple Developer Portal.

  2. Go to Certificates, Identifiers & Profiles > Identifiers.

  3. Click the + button to create a new identifier.

  4. Select App IDs and click Continue.

  5. Select App as the type and click Continue.

  6. Configure your App ID:

FieldValue
DescriptionYour app name (e.g., “My UTXOS App”)
Bundle IDExplicit ID (e.g., com.yourcompany.yourapp)

  1. In the Capabilities section, enable Sign In with Apple.

  2. Click Continue, then Register.

Create a Services ID

  1. Return to Identifiers and click the + button.

  2. Select Services IDs and click Continue.

  3. Configure your Services ID:

FieldValue
DescriptionYour service name (e.g., “My UTXOS App Web”)
IdentifierA unique identifier (e.g., com.yourcompany.yourapp.web)

  1. Click Continue, then Register.

  2. Click on your newly created Services ID to edit it.

  3. Enable Sign In with Apple and click Configure.

  4. Configure the web authentication:

FieldValue
Primary App IDSelect the App ID you created earlier
Domains and Subdomainsutxos.dev
Return URLshttps://utxos.dev/api/auth
  1. Click Save, then Continue, then Save again.

Create a Private Key

  1. Navigate to Keys in the Apple Developer Portal.

  2. Click the + button to create a new key.

  3. Enter a Key Name (e.g., “UTXOS Sign In Key”).

  4. Enable Sign In with Apple and click Configure.

  5. Select your Primary App ID and click Save.

  6. Click Continue, then Register.

  7. Download the private key file (.p8). Store it securely.

🚫

The private key can only be downloaded once. If you lose it, you must create a new key.

  1. Note your Key ID displayed on the confirmation page.

  2. Note your Team ID from the top-right of the Developer Portal (or from Membership details).

Configure UTXOS Dashboard

  1. Open the UTXOS Dashboard and select your project.

  2. Navigate to Settings > Authentication.

  3. Select Apple from the provider list.

  4. Enter your credentials:

FieldValue
Services IDYour Services ID identifier (e.g., com.yourcompany.yourapp.web)
Team IDYour Apple Developer Team ID
Key IDThe Key ID from your private key
Private KeyThe contents of your .p8 private key file

  1. Toggle Enable to activate Apple authentication.

  2. Click Save project settings.

Verify the Integration

  1. Open your application and initiate the wallet connection flow.

  2. Select Login with Apple.

  3. Complete the Apple Sign In process.

  4. Confirm you are redirected back to your application with an active wallet session.

Apple may prompt users to hide their email address. UTXOS handles both real and relay email addresses.

Troubleshooting

”Invalid client_id” Error

The Services ID does not match your configuration. Verify you are using the Services ID identifier (not the App ID) in the UTXOS dashboard.

”redirect_uri is not valid” Error

The Return URL in your Services ID configuration does not match. Ensure https://utxos.dev/api/auth is configured exactly as shown.

”Invalid key” Error

Check that you pasted the entire contents of the .p8 file, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

Users See “Sign in with Apple is not available”

This can occur if:

  • The Services ID is not properly configured
  • The domain utxos.dev is not verified
  • Your Apple Developer membership has lapsed

Private Email Relay Issues

If users choose to hide their email, Apple provides a relay address. Ensure your application handles @privaterelay.appleid.com email addresses.

Apple-Specific Considerations

Email Privacy

Apple allows users to hide their real email address. Your application receives a unique relay address that forwards to the user’s actual email.

Name Sharing

Apple only shares the user’s name on the first authorization. Subsequent sign-ins do not include name data. Store user names on first login.

Account Revocation

Users can revoke your app’s access from their Apple ID settings. Handle authentication failures gracefully for previously authenticated users.

Next Steps

X (Twitter)Third-Party Auth