---
title: "sdk/macos"
description: "Swift SDK for macOS using ASWebAuthenticationSession, PKCE S256 authorization code flow, and Keychain token storage. Shares the implementation pattern with sdk/ios."
locale: "en"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/en/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/macos

## Status

Package status is **Implemented · verified locally**. Unit tests (22 passed) run on macOS. Keychain access and the full ASWebAuthenticationSession OAuth callback flow require a running XID instance for L4 verification. Real IdP round-trip is pending manual verification. This page documents implemented behavior; it is not a production-readiness claim.

## Requirements

- macOS 13+
- Swift 5.9+ and Xcode 15+
- No third-party dependencies — uses Apple system frameworks (AuthenticationServices, CryptoKit, Security)

## Installation

Add via Swift Package Manager in Package.swift:

```swift
// Package.swift
dependencies: [
.package(url: "https://github.com/StringKe/xid", from: "0.1.0"),
],
targets: [
.target(name: "YourApp", dependencies: [.product(name: "Xid", package: "xid")]),
]
```

## Quick start

```swift
import Xid

let client = XidClient()

// 1. Configure
client.configure(XidOptions(
issuer: URL(string: "https://xid.dev")!,
clientId: "your_client_id",
redirectUri: "yourapp://callback"
))

// 2. Sign in (opens ASWebAuthenticationSession)
let session = try await client.signIn()

// 3. Get a valid access token (auto-refresh)
let token = try await client.getAccessToken()

// 4. Get current session
let current = try await client.getSession()

// 5. Sign out
try await client.signOut()
```

## Core API

| Method | Description |
| --- | --- |
| `configure(_ options:)` | Set issuer, clientId, redirectUri, and scopes. Call before all other methods. |
| `signIn() async throws -> XidSession` | Launch ASWebAuthenticationSession, complete PKCE S256 authorization code flow, persist tokens to Keychain, and return a session. |
| `handleRedirect(_ url:) async throws -> XidSession` | Process a redirect URL from an external source and exchange the code for tokens. |
| `getSession() async throws -> XidSession?` | Return the stored session with automatic refresh token rotation if near expiry. |
| `getAccessToken() async throws -> String` | Return a valid access token string, refreshing automatically if needed. |
| `signOut() async throws` | Clear Keychain tokens and revoke the local session. |

## Relationship to sdk/ios

The macOS SDK shares the same Swift implementation pattern as sdk/ios — ASWebAuthenticationSession for browser-based authorization, CryptoKit for PKCE S256, and Keychain for token storage. The two packages target different Apple platform minima and are maintained separately to allow platform-specific entitlement configuration.

## Security

- Public client — no client secret stored or transmitted.
- PKCE S256 only. Server rejects plain challenge method.
- OAuth state generated per request; validated on redirect to prevent CSRF.
- Tokens stored in Keychain with device-only access; not synced to iCloud Keychain.

## Known limitations

- JWKS-backed ES256/RS256 ID token verification and end\_session logout are implemented and locally tested. Real macOS Keychain and IdP round-trip validation is still required before L4 support.
- Shared Swift core extraction with sdk/ios is planned but not yet done — each package carries its own copy of the implementation.

Source: https://xid.dev/sdks/macos/index.mdx