Registrarse

Todo esto se hace en id.costia.app/developer, con tu propia cuenta de Costia. No hay revisión humana.

1. Crear el partner

El nombre que pongas es el que verá tu cliente en la pantalla de consentimiento, junto a «quiere acceder a tu cuenta de Costia». Pon aquel por el que te conocen: es lo único en lo que se apoya para decidir si te autoriza.

Puedes registrar hasta diez partners por cuenta.

2. Verificar tu dominio

Solo si vas a escribir facturas. Para iniciar sesión no hace falta.

Al reclamar un dominio recibes un token, y lo publicas de una de estas dos formas:

_costia-challenge.tutienda.com   TXT   costia-verify-xxxxxxxxxxxx

https://tutienda.com/.well-known/costia-partner

El contenido del fichero es el token, tal cual. Luego pulsas verificar.

Con cualquiera de las dos basta. La comprobación se hace solo por HTTPS, no sigue redirecciones y rechaza direcciones privadas — así que un dominio que apunte a tu red interna no vale como prueba.

Al verificarlo, tu marca queda fijada a lo que demostraste, no a lo que escribiste. Es lo que desbloquea invoices:write.

En el consentimiento, Costia muestra cada dominio real de retorno del cliente. Lleva la insignia Verificado solo cuando coincide con un dominio que has demostrado o es uno de sus subdominios; cualquier otro lleva No verificado. Verificar un dominio no hace que una URL de retorno alojada en otro sitio herede su confianza.

3. Crear el cliente OAuth

Necesitas dos cosas.

El nombre del cliente, que es lo que se lee en el consentimiento.

Las URLs de retorno, que las marca tu framework y no tú. Con Better Auth es https://tu-dominio/api/auth/callback/costia; con NextAuth, /api/auth/callback/costia; con Spring Security, /login/oauth2/code/costia. Tienen que coincidir carácter a carácter, sin comodines ni fragmentos. Los clientes de servidor usan https. Una aplicación nativa pública también puede usar un esquema privado de dominio inverso, por ejemplo com.tutienda.app:/oauth2redirect. Si no coincide, la autorización se rechaza antes de empezar: es lo que impide que un tercero reciba el código en tu nombre.

Elige confidencial si tu cliente vive en un servidor capaz de proteger credenciales. Recibirás el client_id y el client_secret. Elige público para una aplicación instalada: recibe solo client_id y se autentica mediante PKCE, porque un secreto incluido en un binario se puede extraer y no sería secreto.

Un cliente público no puede solicitar invoices:write: cualquiera puede imitar su client_id y Costia no permitiría que escribiese facturas bajo una marca verificada. Tampoco recibe refresh tokens ni puede pedir offline_access; cuando necesite acceso de nuevo debe repetir la autorización. El tipo no se puede cambiar después de crear el cliente: crea otro para migrar entre público y confidencial.

Puedes consultar todos tus client_id, editar el nombre, los scopes y varias URLs exactas de retorno, añadir URLs de retorno tras logout, rotar el secreto o eliminar el cliente. El endpoint OIDC de cierre de sesión es https://id.costia.app/connect/logout.

Qué scopes pedir

Pide solo lo que vayas a usar. Tu cliente puede desmarcar cualquiera menos la identificación, y si desmarca uno se le dice explícitamente qué dejará de poder hacer tu aplicación.

Scope	Para qué	Requisito
`openid`	Identificar la cuenta. Siempre presente	—
`profile`	Leer su nombre	—
`email`	Leer su correo verificado	El correo exacto debe estar verificado
`invoices:read`	Leer sus facturas	—
`invoices:write`	Escribir facturas a tu nombre	Dominio verificado
`offline_access`	Seguir trabajando cuando no esté presente	Solo cliente confidencial

invoices:read e invoices:write son independientes, no una escala. Una tienda escribe y nunca lee; una gestoría lee y nunca escribe. Conceder ambos es una decisión explícita.

Pedir invoices:write sin dominio verificado se rechaza al crear el cliente, no al usarlo — un cliente que nunca recibió el permiso no puede pedirlo después.

Puedes marcar cualquier scope habilitado como obligatorio. Seguirá apareciendo sin marcar: la persona tiene que concederlo voluntariamente, pero no podrá continuar sin él. Si email es obligatorio y su dirección no está verificada, Costia le pedirá entrar con Google o Apple usando esa misma dirección, o enviar un enlace de un solo uso cuando el entorno tenga entrega de correo configurada. El enlace caduca, tiene límite de envíos y solo verifica la dirección exacta a la que se mandó. Apple solo cuenta cuando realmente entrega el correo; uno añadido manualmente después no queda verificado. Cada petición de autorización debe incluir todos los scopes que configuraste como obligatorios; Costia nunca amplía silenciosamente los permisos que pide el cliente.

También puedes proponer una duración por defecto. La persona siempre puede cambiar la fecha o dejar el permiso sin caducidad. Una vez vencido, tendrá que autorizar de nuevo.