document /api/me/invoker, Vault and certificate variables

This repository contains the OpenCAPIF Backoffice Backend service.

Its purpose is to manage OpenCAPIF resources (Invokers, Providers, APIs, and Users), including listing, filtering, and deletion operations, plus authentication and configuration management endpoints.

Its purpose is to manage OpenCAPIF resources (Invokers, Providers, APIs, and Users), including listing, filtering, and deletion operations, plus authentication and configuration management endpoints. It also lets regular users onboard their own API invokers.

## Prerequisites

- If you use the default local OpenCAPIF deployment, no value changes are usually needed.

- If any of those service names are changed in your OpenCAPIF deployment, you must update docker-compose.yml accordingly (for example CAPIF_HOSTNAME, REGISTER_HOSTNAME, VAULT_HOSTNAME, and extra_hosts). This will be improved in future versions.

- CCF_ONBOARDING_URL, CCF_API_ONBOARDING_URL, CCF_PUBLISH_URL, CCF_DISCOVER_URL, and CCF_SECURITY_URL are static per deployment and must match the ccf_* paths returned by CAPIF's /getauth response; a mismatch is logged as a WARNING on login.

- The CSR subject fields can be set via `CERT_ORGANIZATION` (default `Telefonica I+D`), `CERT_ORGANIZATIONAL_UNIT` (`Innovation`), `CERT_LOCALITY` (`Madrid`), `CERT_STATE` (`Madrid`), `CERT_COUNTRY` (`ES`, must be a 2-letter code) and `CERT_EMAIL` (`inno@tid.es`). They have defaults, so they don't need to be set in `docker-compose.yml`.

- `VAULT_ADDR` sets the Vault base URL (e.g. `https://vault.example:8200`). If unset, it defaults to `http://$VAULT_HOSTNAME:$VAULT_PORT`. Note: Vault requests use `verify=False`, so with an `https://` address traffic is encrypted but Vault's certificate is not verified.

- `CERT_ORGANIZATION` (default `Telefonica I+D`), `CERT_ORGANIZATIONAL_UNIT` (`Innovation`), `CERT_LOCALITY` (`Madrid`), `CERT_STATE` (`Madrid`), `CERT_COUNTRY` (`ES`, must be a 2-letter code) and `CERT_EMAIL` (`inno@tid.es`) set the subject of generated CSRs only. They do not appear in issued certificates: the Vault signing role `pki_int/roles/my-ca` has `use_csr_common_name=false` and `use_csr_sans=false`, so the signer sets the CN (e.g. `superadmin`, or the `apiInvokerId` for invokers) and ignores the CSR subject. They have defaults, so they don't need to be set in `docker-compose.yml`.

- `VAULT_ADDR` sets the Vault base URL (e.g. `https://vault.example:8200`). If unset, it defaults to `http://$VAULT_HOSTNAME:$VAULT_PORT`.

- `VAULT_CACERT` (optional) is the path to a CA bundle used to verify Vault's TLS certificate. If unset, default verification is used, so an `https://` Vault with a private CA requires it. Has no effect with an `http://` address.

Example /etc/hosts entries for a default local setup:

## Authentication

- Login endpoint currently validates fixed credentials (superadmin/admin).

- POST /api/login validates `superadmin` locally; all other users are authenticated against the CAPIF register service (`/getauth`). For those users, the CAPIF access token and the user's CAPIF uuid are embedded in the issued JWT (`capif_token`, `capif_uuid`).

- POST /api/login returns access_token and refresh_token.

- Most endpoints require a Bearer access token in the Authorization header.

- POST /api/refresh requires a valid refresh token.

- POST /api/refresh

- GET /api/auth/me

### Me (user-scoped)

Endpoints acting on behalf of the logged-in user. They require a valid access token but are not admin-only; only accounts with CAPIF credentials can use them (superadmin gets 403).

- POST /api/me/invoker

  - Onboards an API invoker in CAPIF for the logged-in user: generates a key pair and CSR, onboards via CCF using the user's CAPIF token, and stores the private key and certificate bundle in Vault under `secret/backoffice/users/{uuid}/invokers/{apiInvokerId}`.

  - Body: `{"apiInvokerInformation": "...", "notificationDestination": "..."}`

  - Responses: `201` `{"apiInvokerId": "..."}`; `400` missing fields; `403` account has no CAPIF credentials; `502` CCF could not be reached, rejected the onboarding, or returned an unexpected response; `500` credentials could not be stored in Vault. On `500` a rollback of the invoker in CCF is attempted; if it fails, the invoker remains in CCF and is logged for admin cleanup.

### Events and Monitoring

- GET /api/events/{id}

- Authentication with access and refresh JWT tokens.

- Resource management for Invokers, Providers, APIs, and Users.

- Configuration and Register configuration management endpoints.

- User-scoped invoker onboarding (`POST /api/me/invoker`), with credentials stored in Vault.

In progress:

- local_build.sh version automation and registry push flow.