issuers

Creates, updates, deletes, gets or lists an issuers resource.

Overview

Name	issuers
Type	Resource
Id	vercel.kms.issuers

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string
name	string
owner_id	string	(wire: ownerId)
algorithm	string	(ES256, ES384, ES512, EdDSA, PS256, PS384, PS512, RS256, RS384, RS512)
claims_schema	object	(wire: claimsSchema)
created_at	string	(wire: createdAt)
managed_by	string	(wire: managedBy)
origin	string	(external, vercel)
policies	array
signing_keys	array	(wire: signingKeys)
updated_at	string	(wire: updatedAt)

list

Name	Datatype	Description
id	string
name	string
owner_id	string	(wire: ownerId)
algorithm	string	(ES256, ES384, ES512, EdDSA, PS256, PS384, PS512, RS256, RS384, RS512)
claims_schema	object	(wire: claimsSchema)
created_at	string	(wire: createdAt)
managed_by	string	(wire: managedBy)
origin	string	(external, vercel)
policies	array
signing_keys	array	(wire: signingKeys)
updated_at	string	(wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	issuer_id	team_id, slug	Retrieve a single KMS issuer by its ID. Accepts either a team bearer token (existing path) or an OIDC token authorized by one of the issuer's policies (e.g. a connex-grant token). The OIDC path returns the issuer without policies, since a policy token only proves signing access, not management access.
list	select		limit, next, team_id, slug	Retrieve the list of KMS issuers that belong to the authenticated team. The results are paginated.
create	insert	name	team_id, slug	Create a new KMS issuer for the authenticated team. An issuer owns the asymmetric signing keys that are used to sign tokens and messages.
update	update	issuer_id	team_id, slug	Update a KMS issuer's name or claims schema.
delete	delete	issuer_id	team_id, slug	Delete a KMS issuer and its signing keys.
sign_message	exec	issuer_id, message		Sign a raw message with a KMS issuer's active signing key. Authenticate the request with a Vercel OIDC token in the Authorization: Bearer header; the issuer's policies decide which workloads are allowed to sign.
sign_token	exec	issuer_id		Sign a JWT with a KMS issuer's active signing key. Authenticate the request with a Vercel OIDC token in the Authorization: Bearer header; the issuer's policies decide which workloads are allowed to sign.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
issuer_id	string	The ID of the issuer.
limit	integer	Maximum number of issuers to return.
next	string	Continuation cursor to retrieve the next page of results.
slug	string	The Team slug to perform the request on behalf of.
team_id	string	The Team identifier to perform the request on behalf of. (wire: teamId)

SELECT examples

get

Retrieve a single KMS issuer by its ID. Accepts either a team bearer token (existing path) or an OIDC token authorized by one of the issuer's policies (e.g. a connex-grant token). The OIDC path returns the issuer without policies, since a policy token only proves signing access, not management access.

SELECT
id,
name,
owner_id,
algorithm,
claims_schema,
created_at,
managed_by,
origin,
policies,
signing_keys,
updated_at
FROM vercel.kms.issuers
WHERE issuer_id = '{{ issuer_id }}' -- required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

list

Retrieve the list of KMS issuers that belong to the authenticated team. The results are paginated.

SELECT
id,
name,
owner_id,
algorithm,
claims_schema,
created_at,
managed_by,
origin,
policies,
signing_keys,
updated_at
FROM vercel.kms.issuers
WHERE limit = '{{ limit }}'
AND next = '{{ next }}'
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

INSERT examples

create

Create a new KMS issuer for the authenticated team. An issuer owns the asymmetric signing keys that are used to sign tokens and messages.

INSERT INTO vercel.kms.issuers (
name,
algorithm,
claims_schema,
policy,
import_key,
import_key_id,
team_id,
slug
)
SELECT 
'{{ name }}' /* required */,
'{{ algorithm }}',
'{{ claims_schema }}',
'{{ policy }}',
'{{ import_key }}',
'{{ import_key_id }}',
'{{ team_id }}',
'{{ slug }}'
RETURNING
id,
name,
owner_id,
algorithm,
claims_schema,
created_at,
managed_by,
origin,
policies,
signing_keys,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: issuers
props:
  - name: name
    value: "{{ name }}"
    description: |
      The name of the issuer.
  - name: algorithm
    value: "{{ algorithm }}"
    description: |
      The signing algorithm to use for the issuer. EdDSA is not accepted for new issuers.
    valid_values: ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'ES256', 'ES384', 'ES512']
    default: RS512
  - name: claims_schema
    value: "{{ claims_schema }}"
    description: |
      A JSON Schema used to validate the resolved token claims when signing tokens for this issuer.
  - name: policy
    value:
      kind: "{{ kind }}"
      teamId: "{{ teamId }}"
      projectId: "{{ projectId }}"
      environments:
        - "{{ environments }}"
      tokenClaims: "{{ tokenClaims }}"
      clientId: "{{ clientId }}"
  - name: import_key
    value: "{{ import_key }}"
    description: |
      The PEM-encoded private key to use for the issuer.
  - name: import_key_id
    value: "{{ import_key_id }}"
    description: |
      The key id to use as the imported key's JWT/JWKS `kid`. Only allowed when `importKey` is provided. Not required to be unique; the addressable key id is the server-minted `keyId` returned in the response.
  - name: team_id
    value: "{{ team_id }}"
    description: The Team identifier to perform the request on behalf of.
    description: The Team identifier to perform the request on behalf of.
  - name: slug
    value: "{{ slug }}"
    description: The Team slug to perform the request on behalf of.
    description: The Team slug to perform the request on behalf of.

UPDATE examples

update

Update a KMS issuer's name or claims schema.

UPDATE vercel.kms.issuers
SET 
name = '{{ name }}',
claims_schema = '{{ claims_schema }}'
WHERE 
issuer_id = '{{ issuer_id }}' --required
AND team_id = '{{ team_id}}'
AND slug = '{{ slug}}'
RETURNING
id,
name,
owner_id,
algorithm,
claims_schema,
created_at,
managed_by,
origin,
policies,
signing_keys,
updated_at;

DELETE examples

delete

Delete a KMS issuer and its signing keys.

DELETE FROM vercel.kms.issuers
WHERE issuer_id = '{{ issuer_id }}' --required
AND team_id = '{{ team_id }}'
AND slug = '{{ slug }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

sign_message

Sign a raw message with a KMS issuer's active signing key. Authenticate the request with a Vercel OIDC token in the Authorization: Bearer header; the issuer's policies decide which workloads are allowed to sign.

EXEC vercel.kms.issuers.sign_message 
@issuer_id='{{ issuer_id }}' --required 
@@json=
'{
"message": "{{ message }}"
}'
;

sign_token

Sign a JWT with a KMS issuer's active signing key. Authenticate the request with a Vercel OIDC token in the Authorization: Bearer header; the issuer's policies decide which workloads are allowed to sign.

EXEC vercel.kms.issuers.sign_token 
@issuer_id='{{ issuer_id }}' --required 
@@json=
'{
"claims": "{{ claims }}", 
"headers": "{{ headers }}", 
"ttl": {{ ttl }}
}'
;