Obtener un token

Todo lo que hay bajo /public/v1 —salvo las categorías— se llama con el token de acceso que recibiste al terminar el flujo de OAuth, en la cabecera:

Authorization: Bearer <access_token>

La dirección base es:

https://api.costia.app

Caducidad y refresco

Un token de acceso dura quince minutos. Con el scope offline_access recibes además un refresh token, válido noventa días, con el que obtienes uno nuevo sin que la persona esté delante.

Los refresh token rotan: cada uso devuelve uno nuevo y anula el anterior. Guarda siempre el último. La ventaja es que un refresh token filtrado deja de servir en cuanto lo usa su dueño legítimo.

Si tu librería gestiona el ciclo por ti, no tienes que hacer nada. Con Better Auth:

const { accessToken } = await auth.api.getAccessToken({
  body: { providerId: 'costia' },
  headers: request.headers,
});

Refresca solo cuando queda poco para caducar.

Errores de autenticación

Código	Qué significa
401 UNAUTHORIZED	El token no es uno emitido por Costia a un cliente registrado
403 ACCESS_DENIED	El token es válido pero le falta el scope que pide el endpoint
403 NOT_A_PARTNER_CLIENT	El cliente no tiene identidad de partner: puede identificar personas, no actuar como comercio

La lista completa está en Errores.