Service Accounts API
Manage service accounts and their API keys: create, list, update, rotate, and revoke.
List service accounts
Returns all service accounts in the authenticated organization. Requires human authentication with a Manager role or higher; service account credentials are rejected.
curl 'https://api.factory.ai/api/v0/service-accounts' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Responses
Allowed values
Unix epoch milliseconds when the service account was created
Unix epoch milliseconds when the service account was last updated
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Create a service account
Creates a new service account in the authenticated organization. Requires human authentication with a Manager role or higher; service account credentials are rejected.
curl -X POST 'https://api.factory.ai/api/v0/service-accounts' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Request body
Allowed values
Responses
Allowed values
Unix epoch milliseconds when the service account was created
Unix epoch milliseconds when the service account was last updated
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
409Response for status 409
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Get a service account
Returns a single service account by ID. Requires human authentication with a Manager role or higher; service account credentials are rejected.
curl 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Service account ID
Responses
Allowed values
Unix epoch milliseconds when the service account was created
Unix epoch milliseconds when the service account was last updated
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Update a service account
Updates a service account description or status. Name is immutable. Requires human authentication with a Manager role or higher; service account credentials are rejected.
curl -X PATCH 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Service account ID
Request body
Allowed values
Responses
Allowed values
Unix epoch milliseconds when the service account was created
Unix epoch milliseconds when the service account was last updated
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Delete a service account
Soft-deletes a service account. Tears down all computers owned by the SA and purges stored git credentials (best-effort). Requires human authentication with a Manager role or higher; service account credentials are rejected.
curl -X DELETE 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Service account ID
Responses
Service account ID that was deleted
Always true; present so clients can distinguish a 200 delete from a 200 get
Allowed values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
List service account API keys
Returns all API keys for a service account, active and inactive. Each item carries `isRevoked`, `expiresAt`, and `revokedAt` so clients can split them into active/inactive views.
curl 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}/api-keys' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Service account ID
Responses
API key ID
Human-readable name for the key
Non-reversible suffix for display
Unix epoch milliseconds when the key was created
Unix epoch milliseconds when the key expires, if set
Whether the key has been revoked (soft-deleted)
Unix epoch milliseconds when the key was revoked, if revoked
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Create a service account API key
Mints a new API key for a service account and returns the one-time key value. The value is shown only once and cannot be retrieved later.
curl -X POST 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}/api-keys' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Service account ID
Request body
Responses
API key ID
One-time presentation key value, returned only on creation
Non-reversible suffix for display
Human-readable name for the key
Unix epoch milliseconds when the key expires, if set
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
402Response for status 402
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
409Response for status 409
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Revoke a service account API key
Revokes an API key for a service account. Once revoked, the key can no longer authenticate. Idempotent.
curl -X POST 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}/api-keys/{keyId}/revoke' \
-H 'Authorization: Bearer $FACTORY_API_KEY'Parameters
Service account ID
API key ID
Responses
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
Rotate a service account API key
DESTRUCTIVE: atomically revokes the existing key and issues a replacement that inherits its name, returning the new one-time key value (shown only once). The previous key stops authenticating the instant this call succeeds, so any client still using it will immediately start failing with 401. Update every consumer with the new value before rotating, or set `gracePeriodMinutes` to keep the old key valid for a short overlap window.
curl -X POST 'https://api.factory.ai/api/v0/service-accounts/{serviceAccountId}/api-keys/{keyId}/rotate' \
-H 'Authorization: Bearer $FACTORY_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ ... }'Parameters
Service account ID
API key ID
Request body
How long (0-10 minutes) the rotated-from key stays valid after rotation. Omit or 0 revokes it immediately. Rejected with a 400 if the key would expire before the grace window ends (the grace period never extends a key lifetime).
Responses
API key ID
One-time presentation key value, returned only on creation
Non-reversible suffix for display
Human-readable name for the key
Unix epoch milliseconds when the key expires, if set
400Response for status 400
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
401Response for status 401
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
403Response for status 403
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
404Response for status 404
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
409Response for status 409
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values
500Response for status 500
Human-readable error message
HTTP status code
HTTP status title
Additional error metadata
Values