Ampersand JWT Key API
The JWT Key API from Ampersand — 2 operation(s) for jwt key.
OpenAPI Specification
openapi: 3.0.1
info:
title: Ampersand public API Key JWT Key API
version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: JWT Key
paths:
/projects/{projectIdOrName}/jwt-keys:
post:
summary: Ampersand Create a New JWT Key
description: Creates a new JWT key for the specified project with RSA public key for token verification
operationId: createJWTKey
tags:
- JWT Key
parameters:
- name: projectIdOrName
in: path
required: true
schema:
type: string
description: Ampersand Project ID or name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJWTKeyRequest'
examples:
example1:
summary: Valid RSA JWT key creation
value:
name: production-key-1
algorithm: RSA
publicKeyPem: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6
V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f
-----END PUBLIC KEY-----
'
responses:
'201':
description: JWT key created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/JWTKeyResponse'
examples:
example1:
summary: Successful key creation
value:
kid: 550e8400-e29b-41d4-a716-446655440000
'400':
description: Bad request - validation error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
invalidAlgorithm:
summary: Unsupported algorithm
value:
type: https://httpstatuses.com/400
title: Bad Request
status: 400
detail: unsupported algorithm
validationIssues:
- field: algorithm
value: ECDSA
detail: only RSA algorithm is supported
remedy: use 'RSA' as the algorithm
invalidPublicKey:
summary: Invalid public key format
value:
type: https://httpstatuses.com/400
title: Bad Request
status: 400
detail: invalid public key
validationIssues:
- field: publicKeyPem
detail: invalid RSA public key in PEM format
remedy: provide a valid RSA public key in PEM format
'404':
description: Project not found
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
projectNotFound:
summary: Project does not exist
value:
type: https://httpstatuses.com/404
title: Not Found
status: 404
detail: project not found
validationIssues:
- field: projectId
detail: project not found
remedy: check the project ID and try again
'500':
description: Internal server error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
get:
summary: Ampersand List JWT Keys
description: Retrieves all JWT keys for the specified project, with optional filtering for active keys only
operationId: listJWTKeys
tags:
- JWT Key
parameters:
- name: projectIdOrName
in: path
required: true
schema:
type: string
description: Ampersand Project ID or name.
- name: active
in: query
description: Filter to only return active JWT keys
required: false
schema:
type: boolean
default: false
example: true
responses:
'200':
description: List of JWT keys retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JWTKey'
examples:
example1:
summary: Multiple JWT keys
value:
- id: 550e8400-e29b-41d4-a716-446655440000
projectId: 123e4567-e89b-12d3-a456-426614174000
label: production-key-1
algorithm: RSA
publicKeyPem: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
-----END PUBLIC KEY-----
'
active: true
createTime: '2024-01-15T10:30:00Z'
updateTime: '2024-01-15T10:30:00Z'
- id: 550e8400-e29b-41d4-a716-446655440001
projectId: 123e4567-e89b-12d3-a456-426614174000
label: development-key-1
algorithm: RSA
publicKeyPem: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5g6xh6m3iLtUfOqn/W52
-----END PUBLIC KEY-----
'
active: false
createTime: '2024-01-10T08:15:00Z'
updateTime: '2024-01-12T14:20:00Z'
emptyList:
summary: No JWT keys found
value: []
'400':
description: Bad request - invalid project ID
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'500':
description: Internal server error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
/projects/{projectIdOrName}/jwt-keys/{keyId}:
get:
summary: Ampersand Get a Specific JWT Key
description: Retrieves a specific JWT key by its ID within the specified project
operationId: getJWTKey
tags:
- JWT Key
parameters:
- name: projectIdOrName
in: path
required: true
schema:
type: string
description: Ampersand Project ID or name.
- name: keyId
in: path
required: true
schema:
type: string
description: The JWT key ID.
responses:
'200':
description: JWT key retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/JWTKey'
examples:
example1:
summary: Single JWT key details
value:
id: 550e8400-e29b-41d4-a716-446655440000
projectId: 123e4567-e89b-12d3-a456-426614174000
label: production-key-1
algorithm: RSA
publicKeyPem: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
-----END PUBLIC KEY-----
'
active: true
createTime: '2024-01-15T10:30:00Z'
updateTime: '2024-01-15T10:30:00Z'
'404':
description: JWT key not found
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
keyNotFound:
summary: Key does not exist
value:
type: https://httpstatuses.com/404
title: Not Found
status: 404
detail: JWT key not found
remedy: check the key ID and project ID are both correct, and try again
'500':
description: Internal server error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
patch:
summary: Ampersand Update a JWT Key
description: Updates specific fields of a JWT key using field masks. Currently supports updating the 'active' status and 'name' field.
operationId: updateJWTKey
tags:
- JWT Key
parameters:
- name: projectIdOrName
in: path
required: true
schema:
type: string
description: Ampersand Project ID or name.
- name: keyId
in: path
required: true
schema:
type: string
description: The JWT key ID.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchJWTKeyRequest'
examples:
deactivateKey:
summary: Deactivate a JWT key
value:
updateMask:
- active
jwtKey:
active: false
renameKey:
summary: Rename a JWT key
value:
updateMask:
- name
jwtKey:
name: updated-key-name
updateMultiple:
summary: Update both name and active status
value:
updateMask:
- active
- name
jwtKey:
active: false
name: deprecated-key
responses:
'200':
description: JWT key updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/JWTKey'
examples:
example1:
summary: Updated JWT key
value:
id: 550e8400-e29b-41d4-a716-446655440000
projectId: 123e4567-e89b-12d3-a456-426614174000
label: updated-key-name
algorithm: RSA
publicKeyPem: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
-----END PUBLIC KEY-----
'
active: false
createTime: '2024-01-15T10:30:00Z'
updateTime: '2024-01-16T15:45:00Z'
'400':
description: Bad request - invalid update mask or missing project/key ID
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
invalidMask:
summary: Invalid update mask
value:
type: https://httpstatuses.com/400
title: Bad Request
status: 400
detail: Invalid update mask
remedy: 'Allowed masks: ''active'' and ''name'''
'404':
description: JWT key not found
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
'422':
description: Unprocessable entity - value not found for mask
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
missingValue:
summary: Missing value for update mask
value:
type: https://httpstatuses.com/422
title: Unprocessable Entity
status: 422
detail: value not found for mask
validationIssues:
- field: jwtKey
detail: required field missing for specified mask
'500':
description: Internal server error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
delete:
summary: Ampersand Delete a JWT Key
description: Permanently deletes a JWT key from the specified project
operationId: deleteJWTKey
tags:
- JWT Key
parameters:
- name: projectIdOrName
in: path
required: true
schema:
type: string
description: Ampersand Project ID or name.
- name: keyId
in: path
required: true
schema:
type: string
description: The JWT key ID.
responses:
'204':
description: JWT key deleted successfully (no content)
'404':
description: JWT key not found
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
examples:
keyNotFound:
summary: Key does not exist
value:
type: https://httpstatuses.com/404
title: Not Found
status: 404
detail: JWT key not found
remedy: check the key ID and project ID are both correct, and try again
'500':
description: Internal server error
content:
application/json:
schema:
$ref: ../problem/problem.yaml#/components/schemas/ApiProblem
components:
schemas:
PatchJWTKeyRequest:
type: object
required:
- updateMask
- jwtKey
properties:
updateMask:
type: array
description: List of field paths to update (currently supports 'active' and 'name')
items:
type: string
enum:
- active
- label
minItems: 1
example:
- active
- label
jwtKey:
type: object
description: Object containing the fields to update with their new values
additionalProperties: true
properties:
active:
type: boolean
description: New active status for the JWT key
example: false
label:
type: string
description: New label for the JWT key
example: updated-key-name
example:
active: false
name: updated-key-name
JWTKeyResponse:
type: object
required:
- kid
properties:
kid:
type: string
format: uuid
description: The unique key identifier (key ID) for the created JWT key
example: 550e8400-e29b-41d4-a716-446655440000
JWTKey:
type: object
required:
- id
- projectId
- label
- algorithm
- publicKeyPem
- active
- createTime
- updateTime
properties:
id:
type: string
format: uuid
description: Unique identifier for the JWT key
example: 550e8400-e29b-41d4-a716-446655440000
projectId:
type: string
format: uuid
description: The project this JWT key belongs to
example: 123e4567-e89b-12d3-a456-426614174000
label:
type: string
description: Human-readable name for the JWT key
example: production-key-1
algorithm:
type: string
description: The cryptographic algorithm used
enum:
- RSA
example: RSA
publicKeyPem:
type: string
description: RSA public key in PEM format
format: pem
example: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
-----END PUBLIC KEY-----
'
active:
type: boolean
description: Whether the JWT key is currently active and can be used for verification
example: true
createTime:
type: string
format: date-time
description: Timestamp when the JWT key was created
example: '2024-01-15T10:30:00Z'
updateTime:
type: string
format: date-time
description: Timestamp when the JWT key was last updated
example: '2024-01-15T10:30:00Z'
CreateJWTKeyRequest:
type: object
required:
- label
- algorithm
- publicKeyPem
properties:
label:
type: string
description: Human-readable label for the JWT key
minLength: 1
maxLength: 255
example: production-key-1
algorithm:
type: string
description: The cryptographic JWT signing algorithm (currently only RS256 is supported)
enum:
- RS256
example: RS256
publicKeyPem:
type: string
description: RSA public key in PEM format for JWT signature verification
format: pem
example: '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6
V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f
-----END PUBLIC KEY-----
'
securitySchemes:
APIKeyHeader:
type: apiKey
name: X-Api-Key
in: header
Bearer:
type: http
scheme: bearer
bearerFormat: JWT