Apple Sign In

Mushu provides Apple Sign In authentication for both iOS apps and web applications. Users authenticate once with their Apple ID and receive JWT tokens for API access.

What This Is

Apple Sign In is Apple's authentication service that lets users sign in with their Apple ID. Mushu handles the OAuth flow and token management, so you get simple JWTs to use in your app.

When to Use

• You're building an iOS app and want simple, secure authentication
• You want users to sign in with their existing Apple ID
• You need the same identity across iOS app and web services

iOS Integration

Native Sign In

Use Apple's AuthenticationServices framework in your iOS app:

import AuthenticationServices

class SignInController: NSObject, ASAuthorizationControllerDelegate {
    func signInWithApple() {
        let request = ASAuthorizationAppleIDProvider().createRequest()
        request.requestedScopes = [.email, .fullName]

        let controller = ASAuthorizationController(authorizationRequests: [request])
        controller.delegate = self
        controller.performRequests()
    }

    func authorizationController(controller: ASAuthorizationController,
                                  didCompleteWithAuthorization authorization: ASAuthorization) {
        guard let appleIDCredential = authorization.credential as? ASAuthorizationAppleIDCredential,
              let identityToken = appleIDCredential.identityToken,
              let tokenString = String(data: identityToken, encoding: .utf8) else {
            return
        }

        // Exchange the Apple token for Mushu tokens
        exchangeToken(identityToken: tokenString)
    }
}

Token Exchange

Exchange the Apple identity token for Mushu access tokens:

func exchangeToken(identityToken: String) {
    let url = URL(string: "https://auth.mushucorp.com/auth/apple/callback")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let body = ["id_token": identityToken]
    request.httpBody = try? JSONEncoder().encode(body)

    URLSession.shared.dataTask(with: request) { data, response, error in
        guard let data = data,
              let tokens = try? JSONDecoder().decode(TokenResponse.self, from: data) else {
            return
        }

        // Store tokens securely
        KeychainHelper.store(accessToken: tokens.accessToken)
        KeychainHelper.store(refreshToken: tokens.refreshToken)
    }.resume()
}

struct TokenResponse: Codable {
    let accessToken: String
    let refreshToken: String
    let userId: String
}

Web OAuth Flow

For web applications, redirect users to the OAuth authorize endpoint:

https://auth.mushucorp.com/auth/apple/authorize?redirect_uri=YOUR_CALLBACK_URL

After authentication, Apple redirects to your callback URL with tokens:

YOUR_CALLBACK_URL?access_token=xxx&refresh_token=yyy

CLI Login Flow

The Mushu CLI uses this web OAuth flow. When you run mushu auth login, it opens a browser for Apple Sign In and receives tokens via a local callback server.

Token Format

Mushu issues JWTs with the following claims:

Claim	Description
sub	User ID
tid	Tenant ID (for multi-tenant apps)
sid	Session ID
iss	Issuer (auth.mushucorp.com)
exp	Expiration timestamp
iat	Issued at timestamp
user_type	Authentication provider (apple)

Using Tokens

Include the access token in API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

The token is valid for 1 hour. See Sessions for refresh handling.

FAQ

What user data does Mushu store?

Mushu stores the user ID (from Apple), email (if shared), and name (if shared). Apple may provide a private relay email if the user chooses to hide their email.

Can users sign in on multiple devices?

Yes. Each device gets its own session with independent tokens. Logging out on one device doesn't affect others.

What if the user revokes access?

If a user revokes access to your app in their Apple ID settings, Mushu automatically handles it via Apple's Server-to-Server notifications. Any existing tokens issued before revocation will fail validation. The user would need to sign in again to create new tokens.

Server-to-Server Notifications

Apple requires apps using Sign In with Apple to handle account lifecycle events. Mushu handles these automatically at POST /auth/apple/notifications.

Event Types

Event	What Happens
account-delete	User deleted their Apple ID. Account marked deleted, all tokens invalidated.
consent-revoked	User revoked app access in Settings. Account marked revoked, all tokens invalidated.
email-disabled	User disabled email forwarding via private relay. Email status updated.
email-enabled	User re-enabled email forwarding. Email status updated.

Configuration

To receive notifications for your app, configure the webhook URL in the Apple Developer Portal:

1. Go to Certificates, Identifiers & Profiles → Identifiers
2. Select your Primary App ID
3. Enable "Sign in with Apple" capability and click Configure
4. Add the Server-to-Server Notification Endpoint URL: https://auth.mushucorp.com/auth/apple/notifications

Token Invalidation

When a user revokes consent or deletes their account, Mushu records a revoked_at timestamp. Any token with an iat (issued at) before this timestamp will fail validation. This ensures immediate session invalidation without requiring a session store.

Bring Your Own Apple Credentials

By default, Mushu uses shared Apple credentials for authentication. For enterprise customers who need their own app name displayed during sign-in or have compliance requirements, you can configure your own Apple Developer credentials.

Benefits of using your own credentials:

• Your app/company name shown during Apple Sign In
• Direct control over Apple Developer Portal configuration
• Receive S2S notifications at your own tenant endpoint
• Meet enterprise compliance requirements

See Auth Tenants for setup instructions and API reference.

Pricing

• Login: $0.005 per authentication
• Token refresh: Free
• Session management: Free
• Custom credentials: Enterprise plan only

See Pricing for full details and a cost calculator.