OpenMercantil API Credentials API
Account API credential management: list, create, rotate and revoke opaque omk_* API keys. Secrets are returned once and recoverable only via an identical Idempotency-Key replay inside 24 hours.
OpenAPI Specification
openapi: 3.1.0
info:
title: OpenMercantil API Credentials API
version: 1.9.3
summary: Versioned public-read, browser-account, billing, support and provider-callback contracts.
description: 'Public JSON API for Spanish company information derived from BORME and other public sources.
OpenMercantil is an independent informational service; it is NOT the BOE, BORME or Registro Mercantil
and does NOT replace official certificates or registry extracts.
**Rate limits.** Free: 60 req/min y 200 req/día por IP. Planes superiores (Profesional 5.000 req/día,
MAX 50.000 req/día, Enterprise 500.000+ req/día) según cuenta y API key. Cabeceras `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-OpenMercantil-Plan`, `Retry-After`.
**License and attribution.** Source-specific metadata in each response and the active versioned source
catalog prevails. OpenMercantil does not relicense upstream content under a blanket license. Unknown,
review and restricted datasets are omitted or return `503 legal_layer_unavailable`. BOE/BORME material
is re-used under Ley 37/2007 and its official version remains boe.es. Court judgments are not exposed;
CENDOJ remains citation-index only under CGPJ Reglamento 3/2010.
**Machine-readable catalog (DCAT-AP-ES):** https://openmercantil.es/catalog.rdf'
termsOfService: https://openmercantil.es/terminos-de-uso
contact:
name: OpenMercantil
url: https://openmercantil.es/soporte
email: social@openmercantil.es
license:
name: Source-specific upstream terms; see response catalog metadata
url: https://openmercantil.es/terminos-de-uso
x-publisher:
name: OpenMercantil
url: https://openmercantil.es/
email: social@openmercantil.es
x-spatial: http://publications.europa.eu/resource/authority/country/ESP
x-temporal: 2009-01-01/..
x-language: es
x-dcat-catalog: https://openmercantil.es/catalog.rdf
x-rate-limit:
free:
per_min: 60
per_day: 200
kind: anonymous-ip
profesional:
per_min: 120
per_day: 5000
kind: api-key
max:
per_min: 600
per_day: 50000
kind: api-key
enterprise:
per_min: 1200
per_day: 500000
kind: contract
x-methodology: https://openmercantil.es/metodologia
x-sources: https://openmercantil.es/fuentes
x-corrections: https://openmercantil.es/correcciones
x-contract-status: Public read, browser-account and provider-callback surfaces are explicitly separated
in this contract. Operator/admin routes are excluded. The public MCP consumes only the allowlisted
GET read plane.
x-account-segment-contract:
projection: company_public_v2 immutable corporate sidecar
synchronous_row_cap: 500
bounded_count_cap: 50001
count_semantics: The segment run response count is the number of rows returned, never a global total.
Dataset preview uses total_is_lower_bound=true and total_lower_bound when the bounded count reaches
50001.
related_web_dataset_surface:
preview_path: /mi-cuenta/datasets/preview
export_path: /mi-cuenta/datasets/export.csv
synchronous_export_max_rows: 500
overflow_status: 503
overflow_error: async_export_required
x-company-identity-contract:
version: '1.0'
projection: company_public_v2 immutable generation-bound corporate sidecar
applies_to: Every /api/v1/company/{slug}*, /api/v1/empresa/{slug}* and /api/v1/grafo/{slug} read before
any report, cache, graph or dataset lookup. /api/v1/companies/compare resolves both requested subjects
in one bounded company_public_v2 batch before either row is exposed; MCP company tools inherit these
preflights through REST.
resolution:
published: canonical corporate slug admitted
safe_alias: internally canonicalized and Content-Location emitted
withheld: neutral 404; includes absent, personal and ambiguous/quarantined identities
unavailable: 503 with no-store; clients must not infer absence
search: Exact corporate CIF, exact canonical/safe-alias slug, or bounded name_prefix2 pool scored
in application code. DNI/NIE and ambiguous CIFs return zero items.
public_company_count: company_public_projection_state.row_count
servers:
- url: https://openmercantil.es
description: Production
tags:
- name: API Credentials
paths:
/api/v1/user/api-credentials:
get:
operationId: listUserApiCredentials
x-query-contract:
allowed:
- limit
- cursor
unknown: 400 invalid_parameter
non_scalar: 400 invalid_parameter
lexical: 400 invalid_parameter
range: 422 validation_failed
tags:
- User
- API Credentials
summary: List API credential metadata
description: Account-plane endpoint. Revalidates the session account in users.sqlite and returns
a bounded, signed-cursor page of prefixes, last four characters, scopes and lifecycle state; never
a token or hash.
x-plane: account
security:
- cookieAuth: []
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 50
default: 20
- name: cursor
in: query
description: Opaque signed cursor bound to the authenticated user. Offset pagination is not supported.
schema:
type: string
minLength: 1
maxLength: 256
responses:
'200':
description: Credential metadata and allowed scope catalog
content:
application/json:
schema:
type: object
properties:
credentials:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/ApiCredential'
allowed_scopes:
type: object
description: Scope name to human-readable capability description.
maxProperties: 16
additionalProperties:
type: string
token_visible_once:
type: boolean
const: true
max_active:
type: integer
const: 10
pagination:
type: object
required:
- limit
- has_more
- next_cursor
properties:
limit:
type: integer
minimum: 1
maximum: 50
has_more:
type: boolean
next_cursor:
type:
- string
- 'null'
maxLength: 256
'400':
$ref: '#/components/responses/BadRequest'
'422':
$ref: '#/components/responses/ValidationFailed'
'401':
$ref: '#/components/responses/Unauthorized'
'503':
description: Account, credential schema or cursor-signing service unavailable
post:
operationId: createUserApiCredential
tags:
- User
- API Credentials
summary: Create an API credential
description: Creates a credential once and returns the full token on the original response or an
identical Idempotency-Key retry within 24 hours. Requires session cookie, X-CSRF-Token, a durable
users.sqlite idempotency schema and configured credential/idempotency key material. List/get never
expose the token.
x-plane: account
security:
- cookieAuth: []
parameters:
- $ref: '#/components/parameters/CsrfHeader'
- $ref: '#/components/parameters/AccountIdempotencyKeyHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCredentialCreateRequest'
responses:
'201':
description: Credential created, or its encrypted one-time response replayed for the same key
and payload
headers:
Idempotency-Replayed:
$ref: '#/components/headers/IdempotencyReplayed'
Idempotency-Key-Expires:
$ref: '#/components/headers/IdempotencyKeyExpires'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCredentialOneTimeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Invalid CSRF token
'409':
description: Active credential limit, Idempotency-Key payload conflict, or expired replay window
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: Credential pepper, idempotency encryption keyring/schema, or account service unavailable
/api/v1/user/api-credentials/{id}/rotate:
post:
operationId: rotateUserApiCredential
tags:
- User
- API Credentials
summary: Rotate one API credential
description: Atomically revokes the source and stores the encrypted one-time replacement response
with the same transaction. An identical Idempotency-Key retry within 24 hours returns the same
token without rotating again.
x-plane: account
security:
- cookieAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
minimum: 1
- $ref: '#/components/parameters/CsrfHeader'
- $ref: '#/components/parameters/AccountIdempotencyKeyHeader'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCredentialRotateRequest'
responses:
'200':
description: Rotated, or the exact replacement token replayed for the same key and payload
headers:
Idempotency-Replayed:
$ref: '#/components/headers/IdempotencyReplayed'
Idempotency-Key-Expires:
$ref: '#/components/headers/IdempotencyKeyExpires'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCredentialOneTimeResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Invalid CSRF token
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Idempotency-Key payload conflict or expired replay window
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: Credential pepper, idempotency encryption keyring/schema, or account service unavailable
/api/v1/user/api-credentials/{id}:
delete:
operationId: revokeUserApiCredential
tags:
- User
- API Credentials
summary: Revoke one API credential
x-plane: account
security:
- cookieAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: integer
minimum: 1
- name: X-CSRF-Token
in: header
required: true
schema:
type: string
responses:
'200':
description: Credential revoked
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialRevokedResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Invalid CSRF token
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'503':
description: Account security or credential schema unavailable
components:
headers:
IdempotencyKeyExpires:
description: Unix timestamp after which this key cannot replay the one-time secret and a fresh key
is required.
schema:
type: integer
minimum: 1
IdempotencyReplayed:
description: True when this response was recovered from the durable encrypted replay record for
the same key and payload.
schema:
type: boolean
NoStoreCacheControl:
description: Error responses must not be stored.
schema:
type: string
const: no-store
parameters:
AccountIdempotencyKeyHeader:
name: Idempotency-Key
in: header
required: true
description: Required for account mutations that reveal a secret. Reuse the same key only for an
identical payload. The encrypted response can be replayed for 24 hours; a changed payload or an
expired key returns 409.
schema:
type: string
minLength: 8
maxLength: 128
pattern: ^[A-Za-z0-9][A-Za-z0-9._:\-]{7,127}$
CsrfHeader:
name: X-CSRF-Token
in: header
required: true
description: Fresh token returned by GET /api/v1/user/me for this authenticated session.
schema:
type: string
minLength: 32
maxLength: 256
responses:
BadRequest:
description: Invalid request
headers:
Cache-Control:
$ref: '#/components/headers/NoStoreCacheControl'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found
headers:
Cache-Control:
$ref: '#/components/headers/NoStoreCacheControl'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Rate limit exceeded
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Authentication required (no active session)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ValidationFailed:
description: The query is lexically valid but outside a documented numeric or length bound, or uses
an unsupported indexed combination.
headers:
Cache-Control:
$ref: '#/components/headers/NoStoreCacheControl'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ApiCredential:
type: object
required:
- id
- name
- prefix
- last4
- hint
- scopes
- status
- created_at
properties:
id:
type: integer
minimum: 1
name:
type: string
maxLength: 80
prefix:
type: string
description: Non-secret identification prefix.
last4:
type: string
minLength: 4
maxLength: 4
hint:
type: string
scopes:
type: array
items:
type: string
enum:
- public:read
- companies:read
- people:read
- tenders:read
- legal:read
- integrations:read
- exports:read
- account:read
uniqueItems: true
status:
type: string
enum:
- active
- expired
- revoked
created_at:
type: string
format: date-time
expires_at:
type:
- string
- 'null'
format: date-time
revoked_at:
type:
- string
- 'null'
format: date-time
last_used_at:
type:
- string
- 'null'
format: date-time
rotated_from_id:
type:
- integer
- 'null'
legacy_migrated:
type: boolean
additionalProperties: false
ApiCredentialCreateRequest:
type: object
required:
- scopes
properties:
name:
type: string
minLength: 1
maxLength: 80
scopes:
type: array
items:
type: string
enum:
- public:read
- companies:read
- people:read
- tenders:read
- legal:read
- integrations:read
- exports:read
- account:read
uniqueItems: true
expires_at:
type:
- string
- 'null'
format: date-time
description: Default 90 days; maximum 366 days.
additionalProperties: false
ApiCredentialOneTimeResponse:
type: object
required:
- ok
- credential
- token
- token_visible_once
- idempotency_replayed
- idempotency_expires_at
properties:
ok:
type: boolean
const: true
credential:
$ref: '#/components/schemas/ApiCredential'
token:
type: string
pattern: ^omk_live_[A-Za-z0-9_-]{43}$
readOnly: true
x-sensitive: true
x-visible-once: true
description: Visible only in the original create/rotate response and identical Idempotency-Key
replays during the 24-hour recovery window; never recoverable through list/get.
token_visible_once:
type: boolean
const: true
replaced_credential_id:
type: integer
idempotency_replayed:
type: boolean
readOnly: true
idempotency_expires_at:
type: integer
minimum: 1
readOnly: true
description: Unix timestamp for the encrypted replay window.
additionalProperties: false
ApiCredentialRotateRequest:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 80
scopes:
type: array
items:
type: string
enum:
- public:read
- companies:read
- people:read
- tenders:read
- legal:read
- integrations:read
- exports:read
- account:read
uniqueItems: true
minItems: 1
expires_at:
type:
- string
- 'null'
format: date-time
description: Omitted preserves the current expiry; null resets to the standard 90-day expiry;
maximum 366 days.
additionalProperties: false
CredentialRevokedResponse:
type: object
required:
- ok
- revoked
properties:
ok:
type: boolean
revoked:
type: boolean
additionalProperties: false
ErrorResponse:
type: object
description: Closed compatibility envelope for public/account errors. Route-specific schemas narrow
these fields further where required.
required:
- error
properties:
error:
type: string
minLength: 1
message:
type: string
detail:
type: string
code:
type: string
status:
type:
- integer
- string
projection:
type: string
reason:
type: string
source_catalog_version:
type: string
allowed_parameters:
type: array
uniqueItems: true
items:
type: string
slug:
type: string
key:
type: string
maximum:
type: integer
minimum: 1
parameter:
type: string
fields:
type: array
items:
type: string
max_bytes:
type: integer
minimum: 1
allowed:
type: array
items:
$ref: '#/components/schemas/JsonValue'
valid:
type: array
items:
$ref: '#/components/schemas/JsonValue'
date:
type: string
login_url:
type: string
plan:
type: string
limited_by:
type: string
enum:
- minute
- day
daily_limit:
type: integer
minimum: 1
reset_at:
type: integer
minimum: 1
reset_at_human:
type: string
format: date-time
retry_after_s:
type: integer
minimum: 1
retry_after:
type: integer
minimum: 1
upgrade:
type: string
format: uri
upgrade_url:
type: string
action:
type: string
limit:
type: integer
minimum: 0
remaining:
type: integer
minimum: 0
needed:
type: integer
minimum: 0
shortfall:
type: integer
minimum: 0
ok:
type: boolean
_alias_of:
type: string
additionalProperties: false
JsonValue:
description: A JSON value used only inside explicitly documented extension maps.
oneOf:
- type:
- string
- number
- boolean
- 'null'
- type: array
items:
$ref: '#/components/schemas/JsonValue'
- type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: ob_sess
description: Browser session cookie set after login at /mi-cuenta/login. Mutations also require
X-CSRF-Token header (obtain via GET /api/v1/user/me).