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.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/openmercantil:openmercantil-api-credentials-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.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.
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:
- 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:
- 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:
- 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:
- 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:
schemas:
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
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
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'
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
headers:
NoStoreCacheControl:
description: Error responses must not be stored.
schema:
type: string
const: no-store
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
responses:
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'
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'
BadRequest:
description: Invalid request
headers:
Cache-Control:
$ref: '#/components/headers/NoStoreCacheControl'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Authentication required (no active session)
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'
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
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).
apiKey:
type: apiKey
in: header
name: X-API-Key
description: Optional opaque omk_* API credential for public GETs. Anonymous access remains valid; a credential with the operation's x-api-credential-scope (or public:read) selects its account quota. Never place credentials in query strings.
bearerAuth:
type: http
scheme: bearer
bearerFormat: opaque omk_* credential
description: 'Optional Authorization: Bearer transport for the same opaque omk_* API credential accepted by X-API-Key. It is not a JWT or OAuth access token.'
externalDocs:
description: Documentación narrativa con ejemplos en curl/Python/JavaScript
url: https://openmercantil.es/api/documentacion