DOCSEARCHbyAlgolia
Submit Docs

Alien Developer Documentation

website·Indexed 32 days ago

https://docs.alien.org

Developer resources for integrating Alien SSO, Mini Apps, and Agent ID. Includes guides for OAuth2 human verification, Solana wallet linking via AlienSolanaSsoClient, and the React SDK for building mini apps with in-app payments, push notifications, and haptic feedback. Provides API references for AlienSsoClient, AlienSsoProvider, and the Bridge API, as well as documentation for the Credential Vault and Agent SSO using DPoP-signed calls.

Tokens
47.7K
Snippets
250
Records
291
Agent score
56%

What's inside Alien

  1. Overview of Alien Solana SSO Wallet Linking

    Alien Solana SSO links Solana wallets to verified Alien IDs using on-chain attestations. Unlike standard SSO (JWT), this records the link directly on the Solana blockchain, allowing any dApp or program to verify the identity by reading the attestation.

    Key architectural notes:

    • Single-platform provider: The service is single-tenant; the signing oracle is pinned to one configured platform provider.
    • Linking vs. Authentication: An on-chain attestation proves a wallet was linked to an Alien ID, but it does not prove the current user controls that wallet. Developers should implement a fresh wallet signature check for active authentication.
    • One-shot binding: Only one attestation can exist per wallet. Attempting to link a wallet that is already linked will result in an account already in use error. To re-link, the user must first call the close_attestation instruction.

  2. Understand Alien Providers in Alien SSO

    An Alien Provider is the on-chain representation of an application (web app, mini app, etc.) on the Alien Network. It acts as the application's verified identity and a trust anchor for users.

    Key characteristics:

    • Immutability: Ownership is anchored on the Alien Network to prevent unauthorized tampering.
    • Mutable Metadata: Details like allowed origins, provider URL, name, and logo are managed via the Developer Portal and verified on every request.
    • Management: Providers are created and managed using a developer's Alien ID; all updates must be signed with the creator's private key.

  3. Retrieve launch environment parameters with useLaunchParams

    The useLaunchParams hook provides metadata about the environment in which the mini app was launched, such as the platform (iOS/Android), the host app version, and custom parameters from deeplinks.
    import { useLaunchParams } from '@alien-id/miniapps-react';

function App() {
  const launchParams = useLaunchParams();

  if (!launchParams) {
    return <div>Running outside Alien App</div>;
  }

  return <div>Platform: {launchParams.platform}</div>;
}

  4. Understand the Alien Agent ID authentication flow

    The agent establishes identity using an OIDC flow with PKCE and DPoP. The agent advertises its Ed25519 key's RFC 7638 thumbprint as dpop_jkt during the authorization request. The SSO then mints an id_token where the cnf.jkt claim matches that thumbprint, binding the human owner to the agent's specific keypair. After successful bootstrap, the agent maintains an Ed25519 keypair for signing and an owner-session.json file containing the id_token, access_token, and refresh_token.
    sequenceDiagram
    participant Agent as AI Agent
    participant SSO as Alien SSO
    participant Human as Human (Alien App)

    Agent->>SSO: 1. Start OIDC auth (PKCE + dpop_jkt)
    SSO->>Agent: 2. QR code / deep link
    Human->>SSO: 3. Scan QR, approve
    Agent->>SSO: 4. Poll for authorization
    SSO->>Agent: 5. Poll returns authorization_code
    Agent->>SSO: 6. Exchange code for tokens (with DPoP proof)
    SSO->>Agent: 7. id_token (with cnf.jkt) + access_token + refresh_token
    Agent->>Agent: 8. Verify id_token cnf.jkt, persist owner-session.json

  5. Understand Alien Sessions and Authentication State

    An Alien Session is a unique, cryptographically-verified authentication state created once per user for a specific application (provider). It serves as a permanent, verified connection between a user's Alien ID and the provider.

    Key characteristics include:

    • Uniqueness: Each user has a different session for every app they use; sessions are isolated and cannot be reused across providers.
    • Verification: Sessions are created within secure-execution infrastructure (Frame MPC-based TEEs) and are tamper-proof.
    • User Control: Users manage sessions via their Alien ID and can revoke them at any time.
    • Bot Protection: Because each session is backed by a unique Alien ID (one identity per person), the system prevents Sybil attacks and bot duplication.

  6. Authenticate Alien-aware services using DPoP

    Alien-aware services use RFC 9449 DPoP to authenticate agents. This model binds a human owner to a specific agent key, ensuring that an access token alone is useless without a fresh, per-request proof signed by the agent's Ed25519 key. Every request must include two headers: Authorization: DPoP <access_token> and DPoP: <proof JWT>.

  8. Implement a custom linking UI flow

    If you replace the built-in modal with a custom UI, you must manually handle the attestation transaction. The flow involves:

    1. Generating a deep link via generateDeeplink.
    2. Polling for authorization via pollAuth.
    3. Once status === 'authorized', building the attestation transaction using client.buildCreateAttestationTransaction.
    4. Signing and sending the transaction via the Solana wallet adapter.
    // Inside a custom flow component
const response = await pollAuth(pollingCode);

if (response.status === 'authorized') {
  const connection = connectionAdapter.connection;
  const transaction = await client.buildCreateAttestationTransaction({
    connection,
    payerPublicKey: wallet.publicKey!,
    sessionAddress: response.session_address!,
    oracleSignature: Uint8Array.from(Buffer.from(response.oracle_signature!, 'hex')),
    oraclePublicKey: new PublicKey(Buffer.from(response.oracle_public_key!, 'hex')),
    timestamp: response.timestamp!,
    expiry: 0,
  });

  const { blockhash } = await connection.getLatestBlockhash();
  transaction.recentBlockhash = blockhash;
  transaction.feePayer = wallet.publicKey!;
  const signedTransaction = await wallet.signTransaction!(transaction);
  const signature = await connection.sendRawTransaction(signedTransaction.serialize());
  await connection.confirmTransaction(signature);
}

  9. Check feature support for Clipboard and Haptics

    Both Clipboard and Haptic features have minimum contract version requirements. You can gate your UI using the callable property from the respective hooks or the useCallable hook.
    // Clipboard: available since 0.1.1
// Haptics: available since 0.2.4

const c = useCallable('clipboard:write');
if (!c.callable && c.reason === 'host-outdated') {
  return <p>Update the Alien app to use clipboard features.</p>;
}

  10. Run the Alien Solana SSO Demo locally

    To run the demo application locally, clone the sso-sdk-js repository, build the packages, and configure the environment variables.
    # Clone and install
git clone https://github.com/alien-id/sso-sdk-js.git
cd sso-sdk-js
npm install

# Build packages (required)
npm run build

# Setup demo app
cd ./apps/example-solana-sso-app/
cp .env.example .env

# Run app
npm run dev

    Required .env variables:

    • VITE_ALIEN_SSO_BASE_URL: The SSO service base URL.
    • VITE_ALIEN_PROVIDER_ADDRESS: The platform provider address from the Developer Portal.

  11. Sign and submit the attestation transaction

    After receiving authorization from pollAuth(), the transaction must be signed by the user's wallet and submitted to the blockchain.

    Critical Timing: The transaction must be submitted promptly. The create_attestation instruction will revert with TimestampTooOld if the clock differs from the oracle-signed timestamp by more than 300 seconds.

    // Set the blockhash and fee payer
const { blockhash } = await connection.getLatestBlockhash();
transaction.recentBlockhash = blockhash;
transaction.feePayer = userPublicKey;

// Sign with the user's wallet
const signedTransaction = await userWallet.signTransaction(transaction);

// Send and confirm
const signature = await connection.sendRawTransaction(
  signedTransaction.serialize()
);
await connection.confirmTransaction(signature);

  12. Verify Alien auth tokens on the backend

    Use the @alien-id/miniapps-auth-client to verify JWTs sent from the mini app. The client validates the token against the provided audience and fetches public keys from the JWKS endpoint (https://sso.alien-api.com/oauth/jwks by default). The sub claim in the verified token contains the user's unique Alien ID.
    npm install @alien-id/miniapps-auth-client
    import { createAuthClient } from '@alien-id/miniapps-auth-client';

const authClient = createAuthClient({
  audience: 'your-miniapp-provider-address',
});

async function verifyRequest(req: Request) {
  const token = req.headers.get('Authorization')?.replace('Bearer ', '');

  if (!token) {
    throw new Error('Missing authorization token');
  }

  const tokenInfo = await authClient.verifyToken(token);
  // tokenInfo.sub contains the user's unique Alien ID
  return tokenInfo;
}