Kernel Credentials API
Create and manage credentials for authentication.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kernel API Keys Credentials API
description: Developer tools and cloud infrastructure for AI agents to use web browsers
version: 0.1.0
servers:
- url: https://api.onkernel.com
description: API Server
security:
- bearerAuth: []
tags:
- name: Credentials
description: Create and manage credentials for authentication.
paths:
/credentials:
post:
x-hidden: true
operationId: postCredentials
tags:
- Credentials
summary: Create a credential
description: Create a new credential for storing login information.
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCredentialRequest'
responses:
'201':
description: Credential created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.create({\n domain: 'netflix.com',\n name: 'my-netflix-login',\n values: { username: 'user@example.com', password: 'mysecretpassword' },\n});\n\nconsole.log(credential.id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\ncredential = client.credentials.create(\n domain=\"netflix.com\",\n name=\"my-netflix-login\",\n values={\n \"username\": \"user@example.com\",\n \"password\": \"mysecretpassword\",\n },\n)\nprint(credential.id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.New(context.TODO(), kernel.CredentialNewParams{\n\t\tCreateCredentialRequest: kernel.CreateCredentialRequestParam{\n\t\t\tDomain: \"netflix.com\",\n\t\t\tName: \"my-netflix-login\",\n\t\t\tValues: map[string]string{\n\t\t\t\t\"username\": \"user@example.com\",\n\t\t\t\t\"password\": \"mysecretpassword\",\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
get:
x-hidden: true
operationId: getCredentials
tags:
- Credentials
summary: List credentials
description: List credentials in the resolved project. Credential values are not returned.
security:
- bearerAuth: []
parameters:
- name: domain
in: query
required: false
schema:
type: string
description: Filter by domain
- name: limit
in: query
required: false
schema:
type: integer
default: 20
maximum: 100
description: Maximum number of results to return
- name: offset
in: query
required: false
schema:
type: integer
default: 0
description: Number of results to skip
- name: query
in: query
required: false
description: Case-insensitive substring match against credential name or domain. IDs match by exact value.
schema:
type: string
responses:
'200':
description: List of credentials
headers:
X-Has-More:
schema:
type: boolean
description: Whether there are more results
X-Next-Offset:
schema:
type: integer
description: The offset where the next page starts. 0 when there are no more results.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Credential'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const credential of client.credentials.list()) {\n console.log(credential.id);\n}"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\npage = client.credentials.list()\npage = page.items[0]\nprint(page.id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Credentials.List(context.TODO(), kernel.CredentialListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
/credentials/{id_or_name}:
get:
x-hidden: true
operationId: getCredentialByIdOrName
tags:
- Credentials
summary: Get credential by ID or name
description: Retrieve a credential by its ID or name. Credential values are not returned.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Credential ID or name
responses:
'200':
description: Credential details
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.retrieve('id_or_name');\n\nconsole.log(credential.id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\ncredential = client.credentials.retrieve(\n \"id_or_name\",\n)\nprint(credential.id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.Get(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
patch:
x-hidden: true
operationId: patchCredentialByIdOrName
tags:
- Credentials
summary: Update credential
description: Update a credential's name or values. When values are provided, they are merged with existing values (new keys are added, existing keys are overwritten).
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Credential ID or name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCredentialRequest'
responses:
'200':
description: Credential updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst credential = await client.credentials.update('id_or_name');\n\nconsole.log(credential.id);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\ncredential = client.credentials.update(\n id_or_name=\"id_or_name\",\n)\nprint(credential.id)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tcredential, err := client.Credentials.Update(\n\t\tcontext.TODO(),\n\t\t\"id_or_name\",\n\t\tkernel.CredentialUpdateParams{\n\t\t\tUpdateCredentialRequest: kernel.UpdateCredentialRequestParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", credential.ID)\n}\n"
delete:
x-hidden: true
operationId: deleteCredentialByIdOrName
tags:
- Credentials
summary: Delete credential
description: Delete a credential by its ID or name.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Credential ID or name
responses:
'204':
description: Credential deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nawait client.credentials.delete('id_or_name');"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nclient.credentials.delete(\n \"id_or_name\",\n)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Credentials.Delete(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
/credentials/{id_or_name}/totp-code:
get:
x-hidden: true
operationId: getCredentialTotpCodeByIdOrName
tags:
- Credentials
summary: Generate TOTP code
description: Returns the current 6-digit TOTP code for a credential with a configured totp_secret. Use this to complete 2FA setup on sites or when you need a fresh code.
security:
- bearerAuth: []
parameters:
- name: id_or_name
in: path
required: true
schema:
type: string
description: Credential ID or name
responses:
'200':
description: TOTP code generated successfully
content:
application/json:
schema:
type: object
required:
- code
- expires_at
properties:
code:
type: string
description: Current 6-digit TOTP code
example: '847291'
expires_at:
type: string
format: date-time
description: When this code expires (ISO 8601 timestamp)
example: '2025-01-15T10:30:30Z'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Credential not found or has no TOTP secret configured
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.credentials.totpCode('id_or_name');\n\nconsole.log(response.code);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nresponse = client.credentials.totp_code(\n \"id_or_name\",\n)\nprint(response.code)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Credentials.TotpCode(context.TODO(), \"id_or_name\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Code)\n}\n"
components:
responses:
Conflict:
description: Conflict – resource already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InternalError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized – missing or invalid authorization token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad Request – invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden – insufficient permissions or plan
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Application-specific error code (machine-readable)
example: bad_request
message:
type: string
description: Human-readable error description for debugging
example: 'Missing required field: app_name'
details:
type: array
description: Additional error details (for multiple errors)
items:
$ref: '#/components/schemas/ErrorDetail'
inner_error:
$ref: '#/components/schemas/ErrorDetail'
Credential:
type: object
description: A stored credential for automatic re-authentication
required:
- id
- name
- domain
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the credential
example: cred_abc123xyz
name:
type: string
description: Unique name for the credential within the project
example: my-netflix-login
domain:
type: string
description: Target domain this credential is for
example: netflix.com
created_at:
type: string
format: date-time
description: When the credential was created
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
format: date-time
description: When the credential was last updated
example: '2025-01-15T10:30:00Z'
has_values:
type: boolean
description: Whether this credential has stored values (email, password, etc.)
example: true
has_totp_secret:
type: boolean
description: Whether this credential has a TOTP secret configured for automatic 2FA
example: false
value_keys:
type: array
items:
type: string
description: The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses.
example:
- username
- password
sso_provider:
type: string
nullable: true
description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page.
example: google
totp_code:
type: string
description: Current 6-digit TOTP code. Only included in create/update responses when totp_secret was just set.
example: '847291'
totp_code_expires_at:
type: string
format: date-time
description: When the totp_code expires. Only included when totp_code is present.
example: '2025-01-15T10:30:30Z'
additionalProperties: false
UpdateCredentialRequest:
type: object
description: Request to update an existing credential
properties:
name:
type: string
description: New name for the credential
example: my-updated-login
values:
type: object
description: Field name to value mapping. Values are merged with existing values (new keys added, existing keys overwritten).
additionalProperties:
type: string
example:
username: user@example.com
password: newpassword
remove_value_keys:
type: array
items:
type: string
description: Field names to remove from the credential's stored values. Removals are applied before `values` are merged, so a key present in both is kept with its new value.
example:
- old_field
totp_secret:
type: string
description: Base32-encoded TOTP secret for generating one-time passwords. Spaces and formatting are automatically normalized. Set to empty string to remove.
example: JBSWY3DPEHPK3PXP
sso_provider:
type: string
nullable: true
description: If set, indicates this credential should be used with the specified SSO provider. Set to empty string or null to remove.
example: google
additionalProperties: false
CreateCredentialRequest:
type: object
description: Request to create a new credential
required:
- name
- domain
- values
properties:
name:
type: string
description: Unique name for the credential within the project
example: my-netflix-login
domain:
type: string
description: Target domain this credential is for
example: netflix.com
values:
type: object
description: Field name to value mapping (e.g., username, password)
additionalProperties:
type: string
example:
username: user@example.com
password: mysecretpassword
totp_secret:
type: string
description: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic 2FA during login.
example: JBSWY3DPEHPK3PXP
sso_provider:
type: string
description: If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page.
example: google
additionalProperties: false
ErrorDetail:
type: object
properties:
code:
type: string
description: Lower-level error code providing more specific detail
example: invalid_input
message:
type: string
description: Further detail about the error
example: Provided version string is not semver compliant
securitySchemes:
bearerAuth:
type: http
scheme: bearer