Backend API access
A server needs to call Clerk's Backend API to manage users or other resources.
Clerk · Pipe
secretKey
secretKey is the required string option containing your Clerk Secret Key when creating a backend clerkClient. Usually, supply it through the CLERK_SECRET_KEY environment variable.
How it works
secretKey is a required string option for createClerkClient(). It supplies the Clerk Secret Key used by the backend client to access Clerk's Backend API; keeping the value in CLERK_SECRET_KEY avoids embedding the credential directly in source code.
Syntax
createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })Parameters
| Name | Type | Description |
|---|---|---|
options | object | An options object containing the required Clerk Secret Key. |
options.secretKey | string | The Clerk Secret Key used to authenticate the backend client. |
Returns
A configured clerkClient instance for interacting with Clerk's Backend API.
Key points
secretKeyis a required option when constructing a Clerk backend client.- Its value is the Clerk Secret Key for the instance.
- A typical configuration reads the key from the
CLERK_SECRET_KEYenvironment variable. - The key is supplied while instantiating
clerkClient.
Common mistakes
- Do not omit
secretKeywhen creating the client; the options object must include it. - Prefer an environment variable such as
CLERK_SECRET_KEYinstead of hard-coding the secret.
Example: Create a Clerk client with secretKey
import { createClerkClient } from '@clerk/backend'
const clerk = createClerkClient({
secretKey: process.env.CLERK_SECRET_KEY,
})
const user = await clerk.users.getUser('user_123')
console.log(user.id)Creates a Clerk backend client using the server-side secret key, then retrieves a user.
When to use it
Environment-based configuration
Application configuration differs across development, staging, and production.
Service integration
A server-side integration needs a reusable authenticated Clerk client.
Interview questions
QWhat is the type and role of secretKey in createClerkClient()?
secretKey is a required string in the options passed to createClerkClient(). It is the Clerk Secret Key used to instantiate a backend client.
Follow-up: How should the value normally be supplied? Read it from a server-side environment variable such as CLERK_SECRET_KEY and pass that value in the options object.
QShow a recommended way to configure secretKey.
The client can be created with createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }). This keeps the credential outside the application source while allowing the client to call Clerk's Backend API.
Follow-up: What security boundary applies? The key belongs in backend code and should not be exposed to browser-side application code.
QWhy must secretKey be treated as sensitive configuration?
The secret key is associated with the Clerk instance and is used by the backend client for authenticated API access. The documentation identifies it as the Clerk Secret Key.
Follow-up: What alternative can some backend operations use? Where supported, Clerk documents jwtKey as an alternative to secretKey, but that is operation-specific rather than a replacement requirement for this client option.
Related
createClerkClient()clerkClientCLERK_SECRET_KEYpublishableKeyverifyToken()authenticateRequest()