Skip to main content
To obtain a new Client ID, sign up at auth.civic.com to register your application. You can find your unique Client ID to use when integrating our API.For server-side applications: If you need client secret authentication for backend services, you can generate one directly in your dashboard under the Security tab. See our Authentication Flows guide for details on when and how to use client secrets.
Most applications should use our default PKCE authentication flow, as it provides strong security for modern web and mobile apps without requiring you to manage client secrets.We also support client secrets for server-side applications that require traditional OAuth 2.0 compatibility or want to achieve maximum security by combining it with PKCE.To see which method is right for you, see our complete Authentication Flows guide. If you need a client secret, you can generate one directly in your dashboard by navigating to the Security tab and clicking “Generate Client Secret”. Important: The client secret is only displayed once upon generation, so make sure to copy and securely store it immediately. You can always regenerate a new client secret if needed.
Contact our support team in our developer community for assistance in managing or revoking keys associated with your application.
Civic Auth supports Google as an authentication provider. However, Civic is working to add support for other major OIDC-compliant providers, such as Microsoft and Apple. Once available, these can be configured within your integration setup.Contact our team in our developer community and let us know which provider you’d like to see added.
No, but this is coming soon. Currently, we don’t support connecting users’ existing self-custodial wallets. We only support embedded wallets, which are generated on behalf of the user by our non-custodial wallet partner.Neither Civic nor your app ever has access to the wallets’ private keys.For Solana, we expose the Civic embedded wallets via the wallet-adapter interface. This means that Civic will be available as a choice for your users to connect when using @solana/wallet-adapter-react:
In the example above, the user has Phantom installed and can connect their existing Phantom wallets to your dApp via the wallet-adapter. These wallets cannot currently be linked to Civic Auth. When the user selects Civic Auth, they are taken through a social login flow which gives them an embedded wallet generated by our backend, which is then exposed to your dApp via the wallet-adapter interface.For Ethereum, you could use Civic’s embeddedWallet() wagmi connector alongside other connectors like Metamask, so your code can switch between Civic embedded wallets and the user’s other installed wallets. Currently those wallets cannot be linked to the Civic account, they are separate.
Civic Auth wallets are provided through a partnership with metakeep.xyz. These wallets are Externally Owned Accounts (EOAs), which are authenticated by a private key that is held by the Metakeep infrastructure. They are linked to a user’s email address. Users verify ownership of their email by entering a unique email code. Wallet management occurs securely through client-side encryption using keys from our wallet provider.
No, Civic does not own these wallets. Civic Auth provides a non-custodial wallet solution. Civic facilitates wallet creation and management but does not hold custody of assets or keys.
Users do not directly access their private keys. The wallets are secured using HSM, and transactions are authorized through the user’s SSO login credentials. This simplifies user experience and mitigates the risks of mismanaging private keys.
If a user loses access to their SSO (e.g., Google login), Civic Auth’s wallet provider includes a recovery feature to restore wallet access, which works independently of Civic’s infrastructure. Recovery is managed through the provider. Contact our team in our developer community so that we can initiate the wallet recovery process.
Yes. By default, the Client ID retrieved from the dashboard will be configured for any environment. This will allow you to test your implementation before going live to production.You can get your Client ID at https://auth.civic.com/. Check out https://github.com/civicteam/civic-auth-examples to see how an application integrated with Civic Auth functions.
All domains where your application is hosted must be explicitly registered in your Civic Auth dashboard under “Domains” when your app is in production mode. This is required for OAuth 2.0 security - Civic will only redirect to registered domains after authentication.What needs to be registered:
  • Your application’s domain(s) (e.g., https://myapp.com)
  • Your OAuth callback URLs for backend integrations (e.g., https://myapp.com/auth/callback)
Note: The loginSuccessUrl parameter (used to redirect users to a specific page after login) does not need to be registered separately - it’s used for navigation within your already-registered domain.
The approach depends on your application type:

​
Backend Frameworks (Express, Fastify, Hono)

Use the loginSuccessUrl configuration parameter:
const config = {
  clientId: "YOUR_CLIENT_ID",
  redirectUrl: 'https://your-backend.com/auth/callback', // OAuth callback
  loginSuccessUrl: 'https://your-frontend.com/dashboard', // Where to send users after login
};
How it works:
  1. redirectUrl is the OAuth callback where Civic redirects to complete authentication
  2. After your backend processes the callback, it redirects the user to loginSuccessUrl

​
Next.js

Use the loginSuccessUrl configuration parameter in your Next.js config:
const withCivicAuth = createCivicAuthPlugin({
  clientId: "YOUR_CLIENT_ID",
  loginSuccessUrl: "/dashboard", // Where to send users after login
});

​
React / Single Page Applications (SPAs)

Important: loginSuccessUrl is not supported for React or frontend-only SPAs. Instead, use the onSignIn hook:
import { CivicAuthProvider } from "@civic/auth/react";
import { useNavigate } from "react-router-dom";

function App() {
  const navigate = useNavigate();

  const handleSignIn = (error?: Error) => {
    if (!error) {
      navigate("/dashboard"); // Redirect after successful login
    }
  };

  return (
    <CivicAuthProvider 
      clientId="YOUR_CLIENT_ID"
      onSignIn={handleSignIn}
    >
      {/* Your app content */}
    </CivicAuthProvider>
  );
}
For more details, see the React integration documentation.
Civic Auth provides usage data, including logins from the user account and wallet creation events, via the developer dashboard at https://auth.civic.com.
If you’re experiencing any issues integrating Civic Auth, follow the troubleshooting steps below:
1
Verify if your Client ID at https://auth.civic.com/ is valid and set up properly.
2
Check your console and network tabs for errors.
3
If you’re using an application that’s already in production, ensure that all domains or redirect URLs are correctly registered in your app’s configuration. Civic Auth will only redirect to registered domains after login or logout.
If you’ve completed the steps above and still encounter issues, contact Civic in our developer community and provide the following details to help us investigate further:
  • A clear description of exactly what you’re trying to achieve and the issue you’re encountering in doing so
  • At which step in the implementation does the issue arise
  • Screenshots of the error or unexpected behavior
  • Relevant snippets of your code, especially the sections interacting with Civic Auth.
  • Any error messages from the Console and/or Network tabs
Developers can report bugs or suggest new features by contacting Civic in our developer community. Provide as much detail as possible, including logs, screenshots, and steps to reproduce the issue.
While Civic Auth doesn’t have this feature yet, we are actively working to include it in a future version of Civic Auth.
Currently, Civic Auth does not natively support blocking specific wallets or users.
When integrating Civic Auth, you may need to verify the ID token on your backend to authenticate API requests from your frontend.

​
Getting the ID Token

The ID token is exposed on the userContext object in your frontend integration:
import { useUser } from "@civic/auth/react";

function MyComponent() {
  const { idToken } = useUser();

  // Send the idToken to your backend
  fetch('/api/protected', {
    headers: {
      'Authorization': `Bearer ${idToken}`
    }
  });
}

​
Verifying the Token Signature

To verify the token signature on your backend, use the @civic/auth-verify library. This library automatically queries the Civic JWKS endpoint to fetch the public key and verify the token:
npm install @civic/auth-verify
Basic verification:
import { verify } from '@civic/auth-verify';

// In your backend API route
const token = req.headers.authorization?.replace('Bearer ', '');

try {
  const payload = await verify(token);
  console.log('User authenticated:', payload);
  // Payload contains user information like id, email, name, etc.
} catch (error) {
  console.error('Token verification failed:', error);
  // Return 401 Unauthorized
}
Verifying with client ID validation:
import { verify } from '@civic/auth-verify';

const payload = await verify(token, {
  clientId: 'YOUR_CLIENT_ID' // Ensures token was issued for your app
});
The @civic/auth-verify library handles all the complexity of:
  • Fetching the JWKS (JSON Web Key Set) from Civic’s endpoint
  • Caching the keys for performance
  • Verifying the token signature using the public key
  • Validating token expiration and claims
For more details, see the React integration Token Fields section.