Builder provides three types of credentials to authenticate API requests:
- a Public API Key for client-side integrations
- a Private API Key for server-side read access to private content
- Personal Access Tokens for user-scoped, programmatic access.
Understanding when to use each type is essential for building secure integrations.
An API key is an alphanumeric string that you can use to connect your code base with Builder. Use the Builder Public API Key to integrate with Builder.
An example of a Builder API Key is bb209db71e62412dbe0114bdae18fd15.
Tip: The Builder Public API Key is public, meaning that you don't have to keep it private. Because of this, there are no inherent security risks in it being publicly viewable, for example, on GitHub.
To find your Public API Key:
- Within your Builder Space, press
Cmd + k(Mac) orCtrl + k(Windows) to open the Command Palette. - Start to type the letters API into the search field to filter results.
- Click your API key to copy to your clipboard.
Alternatively, find your Public API Key in Space Settings:
- Within your Builder Space, go Space Settings.
- Click the copy icon to the right of the Public API Key field.
The video below shows both ways of finding the Public API Key.
Pass your Public API Key into the Builder SDK when initializing:
// Replace with your Public API Key
builder.init('YOUR_PUBLIC_API_KEY')For more details on using your Public API Key with the Builder SDK, including Angular, see the Using your API Key in your Framework section of Using Builder API Keys.
A Private API Key is a server-side credential that grants write access to your Builder Space. Use Private Keys when you need to:
- Write or update content in your Builder Space programmatically
- Fetch content that should remain private and not be publicly accessible
Only users with Admin permissions can view or create Private Keys.
Tip: Keep your Private API Key secret. Anyone with a Private Key has write access to your Builder content. Only use it in API calls from your server, not calls from public client applications.
To manage the Private Keys for your Space:
- Go to your Space Settings.
- To the right of Private Keys, click the Edit button.
- Create or revoke as many keys as you need.
For more information on how to use Private Keys with models, visit Create a Private Model.
In rare situations, you may need to create a Private Key for your Organization. Follow the same process, but on your Organization's Settings page. For more details on this page, visit Manage your Organization.
The video below shows going to Space Settings, creating, displaying, and copying a Private API Key:
Pass your Private Key in the Authorization header for write operations from your server:
fetch('https://builder.io/api/v1/write/your-model', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_PRIVATE_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ /* content data */ }),
})Personal Access Tokens (PATs) are user-scoped credentials that authenticate API requests on behalf of the user who created them. They are ideal for:
- CI/CD pipelines and automation scripts
- Server-to-server integrations requiring user-level access
- CLI tools and developer tooling
- Scenarios where you want granular, revocable credentials scoped to a specific user
Personal Access Tokens always start with the prefix btk-.
To create a Personal Access Token:
- In Builder, open your user Profile settings, which is located just below Space Settings.
- By Personal Access Tokens, click the Edit button
- Click Create Token and give it a descriptive name.
- Select the desired scopes:
readfor read-only access,writefor read and write access. - Optionally, restrict the token to specific Spaces.
- Click Create and copy the token value immediately—Builder only shows it once.
Important: Builder only shows the raw token value once at creation time. Copy and store it securely—if you lose it, you must revoke it and create a new token.
Include the token in the Authorization header as a Bearer token:
fetch('https://builder.io/api/v1/your-endpoint', {
headers: {
'Authorization': 'Bearer btk-your-personal-access-token',
},
})Personal Access Tokens support two scopes:
read: allows read-only access to content and resources. Use this for fetching content without the ability to make changes.write: allows both read and write access. Required for creating, updating, or deleting content.
You can also restrict a token to specific spaces, limiting its access to only the spaces you designate.
To revoke a Personal Access Token:
- Go to Account Settings > Personal Access Tokens.
- Find the token you want to revoke.
- Click the Revoke button next to the token.
Revoking a token immediately invalidates it. Any integrations using the revoked token will need to be updated with a new token.
Choose the right credential type for your use case:
- Public API Key: use for reading content via the SDK or public API calls. Safe to expose in client-side code.
- Private API Key: use for server-side write operations where user attribution is not needed or fetching private content. Must be kept secret; never expose in client-side code.
- Personal Access Token: preferred method for any workflows that modify settings, or content. Use for user-scoped programmatic access, CI/CD automation, or CLI tools. Provides granular scope control (
readandwrite) and can be revoked independently.