FileRelayDocumentation
Try for Free

Certificates API

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.

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 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

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

{
  "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

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 as a cert.activated event.

POST /api/{userSlug}/{workspaceSlug}/certificates/:id/activate

Example Request

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

{
  "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

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

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

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 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