--- title: Certificates API description: "API endpoints for listing, inspecting, activating, deactivating, and exporting ArchiveLink signing certificates exchanged with SAP." --- # Certificates API The Certificates API exposes the X.509 certificates that FileRelay receives from SAP via the ArchiveLink `putCert` command. Certificates are used to verify signatures on incoming `create`, `update`, and `delete` requests when signature verification is enabled on a source repository. For the conceptual model and how certificates flow from SAP into FileRelay, see [Certificate Management](/docs/sources/certificates). ## Certificate Object | Field | Type | Description | |--------------------------|---------|-----------------------------------------------------------------------------| | `id` | string | FileRelay certificate ID (ULID, prefixed `cert_`) | | `cert_id` | string | The `authId` SAP used when sending the certificate | | `subject` | string | X.509 subject DN | | `issuer` | string | X.509 issuer DN | | `serial_number` | string | Certificate serial number (hex) | | `valid_from` | string | ISO 8601 timestamp | | `valid_to` | string | ISO 8601 timestamp | | `fingerprint_sha256` | string | SHA-256 fingerprint, lowercase hex | | `fingerprint_sha1` | string | SHA-1 fingerprint, lowercase hex | | `public_key_algorithm` | string | e.g., `RSA`, `EC` | | `signature_algorithm` | string | e.g., `SHA256withRSA` | | `is_active` | boolean | Whether this certificate is used during signature verification | | `status` | string | Derived: `active`, `inactive`, or `expired` | | `docs_verified` | integer | Count of documents whose signature was verified with this certificate | | `last_used_at` | string | ISO 8601 timestamp of the last verification, or `null` | | `created_at` | string | ISO 8601 timestamp | | `updated_at` | string | ISO 8601 timestamp | The raw PEM body is **never** returned in standard list/get responses. Use the [Export PEM](#export-certificate-pem) endpoint to fetch it explicitly. ## List Certificates Retrieve all certificates known to the current workspace. ``` GET /api/{userSlug}/{workspaceSlug}/certificates ``` ### Query Parameters | Parameter | Type | Description | Default | |-------------|---------|--------------------------------------------------------------|---------| | `page` | integer | Page number | 1 | | `per_page` | integer | Items per page (max 100) | 25 | | `status` | string | Filter by `active`, `inactive`, or `expired` | -- | | `repo_id` | string | Filter to certificates associated with this `contRep` ID | -- | | `expiring` | integer | Return only certificates expiring within N days | -- | ### Example Request ```bash curl -X GET "https://filerelay.dev/api/acme/production/certificates?status=active&expiring=30" \ -H "Authorization: Bearer fr_live_abc123def456" \ -H "Accept: application/json" ``` ### Example Response ```json { "data": [ { "id": "cert_xyz789", "type": "certificate", "attributes": { "cert_id": "SAP_SYS_PRD", "subject": "CN=SAPSYS, OU=Basis, O=Acme, C=DE", "issuer": "CN=Acme Internal CA, O=Acme, C=DE", "serial_number": "0A1B2C3D4E5F", "valid_from": "2025-06-01T00:00:00Z", "valid_to": "2027-06-01T00:00:00Z", "fingerprint_sha256": "a1b2c3d4e5f60718293a4b5c6d7e8f9012a3b4c5d6e7f80911223344556677", "fingerprint_sha1": "11223344556677889900aabbccddeeff00112233", "public_key_algorithm": "RSA", "signature_algorithm": "SHA256withRSA", "is_active": true, "status": "active", "docs_verified": 14523, "last_used_at": "2026-04-04T10:30:00Z", "created_at": "2025-06-02T08:00:00Z", "updated_at": "2026-04-04T10:30:00Z" } } ], "meta": { "current_page": 1, "per_page": 25, "total": 1 } } ``` ## Get a Single Certificate ``` GET /api/{userSlug}/{workspaceSlug}/certificates/:id ``` ### Example Request ```bash curl -X GET "https://filerelay.dev/api/acme/production/certificates/cert_xyz789" \ -H "Authorization: Bearer fr_live_abc123def456" \ -H "Accept: application/json" ``` Returns the certificate object shown above wrapped in `data`. ## Activate a Certificate Enable a certificate so it can be used to verify incoming ArchiveLink signatures. Activation is also logged to the [audit log](/docs/api/request-viewer) as a `cert.activated` event. ``` POST /api/{userSlug}/{workspaceSlug}/certificates/:id/activate ``` ### Example Request ```bash curl -X POST "https://filerelay.dev/api/acme/production/certificates/cert_xyz789/activate" \ -H "Authorization: Bearer fr_live_abc123def456" \ -H "Accept: application/json" ``` ### Example Response ```json { "data": { "id": "cert_xyz789", "type": "certificate", "attributes": { "is_active": true, "status": "active", "updated_at": "2026-04-04T11:00:00Z" } } } ``` Returns `200 OK`. Activating an already-active certificate is a no-op and still returns `200 OK`. Attempting to activate an expired certificate returns `422 Unprocessable Entity`. ## Deactivate a Certificate Take a certificate out of the verification trust set without deleting it. Use this for rotation: add and activate the new cert, verify documents flow, then deactivate the old cert. ``` POST /api/{userSlug}/{workspaceSlug}/certificates/:id/deactivate ``` ### Example Request ```bash curl -X POST "https://filerelay.dev/api/acme/production/certificates/cert_xyz789/deactivate" \ -H "Authorization: Bearer fr_live_abc123def456" \ -H "Accept: application/json" ``` Returns `200 OK`. Logged as `cert.deactivated` in the audit log. ## Export Certificate PEM Download the raw certificate in PEM format. Useful for archival or for re-uploading to another trust store. ``` GET /api/{userSlug}/{workspaceSlug}/certificates/:id/pem ``` ### Example Request ```bash curl -X GET "https://filerelay.dev/api/acme/production/certificates/cert_xyz789/pem" \ -H "Authorization: Bearer fr_live_abc123def456" \ -o sap_sys_prd.pem ``` ### Response `Content-Type: application/x-pem-file` ``` -----BEGIN CERTIFICATE----- MIIDazCCAlOgAwIBAgIUO... -----END CERTIFICATE----- ``` Requires **Admin** API key permissions because the PEM contains the full public certificate material. ## Delete a Certificate Permanently remove a certificate. Documents previously verified with this certificate retain their verification history; only the trust entry is removed. ``` DELETE /api/{userSlug}/{workspaceSlug}/certificates/:id ``` ### Example Request ```bash curl -X DELETE "https://filerelay.dev/api/acme/production/certificates/cert_xyz789" \ -H "Authorization: Bearer fr_live_abc123def456" ``` Returns `204 No Content` on success. Logged as `cert.deleted` in the audit log. **Warning:** If this is the only active certificate for a source with signature verification enabled, subsequent SAP requests will fail until a new certificate is received via `putCert`. ## Notes on Certificate Creation There is **no `POST /api/{userSlug}/{workspaceSlug}/certificates` endpoint**. Certificates enter FileRelay only through the ArchiveLink `putCert` protocol exchange initiated by SAP (typically via transaction `CSADMIN`). This API surface is intentionally narrow: it lets you inspect, audit, and manage the trust set, but the trust anchor itself must always be established by SAP. See [Certificate Management](/docs/sources/certificates) for the protocol details. ## Status Values | Status | Description | |-----------|-------------------------------------------------------------------| | `active` | `is_active=true` and `valid_to` is in the future | | `inactive` | `is_active=false`, regardless of validity | | `expired` | `valid_to` is in the past (cannot be activated) | ## Next Steps - [Repositories API](/docs/api/repositories) -- Toggle `signature_verification` per source - [Request Viewer API](/docs/api/request-viewer) -- Inspect signature-verification audit events - [Certificate Management](/docs/sources/certificates) -- The dashboard workflow