Autenticación y tokens

La API usa OAuth 2.0 con credenciales de cliente (grant_type=client_credentials).

• Crea credenciales en el portal: API / Desarrolladores → Credenciales. Cada credencial está limitada a una o varias empresas de tu cuenta y a una clase de ambiente (test o production).
• El secreto se muestra una sola vez. Gravitas solo guarda su huella; nunca podemos volver a mostrártelo.
• El token dura 15 minutos. Pide uno nuevo cuando expire; no hace falta un token de refresco.
• Envía el token en cada llamada: Authorization: Bearer <token>.

curl

# Obtener un token de acceso (válido 15 minutos). Reemplace YOUR_CLIENT_SECRET por su secreto.
curl -s -X POST "https://tuempresa.gravitastec.com/api/v1/oauth/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"
# Guarde el valor de access_token: export TOKEN=...

C#

// Obtener un token de acceso (válido 15 minutos).
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var api = new HttpClient { BaseAddress = new Uri("https://tuempresa.gravitastec.com/api/v1/") };
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = "YOUR_CLIENT_ID",
    ["client_secret"] = Environment.GetEnvironmentVariable("GRAVITAS_CLIENT_SECRET") ?? "YOUR_CLIENT_SECRET",
});
var tokenResponse = await api.PostAsync("oauth/token", form);
tokenResponse.EnsureSuccessStatusCode();
var token = JsonDocument.Parse(await tokenResponse.Content.ReadAsStringAsync()).RootElement.GetProperty("access_token").GetString();
api.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
Console.WriteLine("Token obtenido; expira en 15 minutos.");

JavaScript

// Obtener un token de acceso (válido 15 minutos). Node 20+.
const baseUrl = 'https://tuempresa.gravitastec.com/api/v1';
const tokenResponse = await fetch(`${baseUrl}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: process.env.GRAVITAS_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET',
  }),
});
const { access_token: token } = await tokenResponse.json();
const auth = { Authorization: `Bearer ${token}` };
console.log('Token obtenido');

Rotar y revocar

• Rotar genera un secreto nuevo y mantiene el anterior válido 24 horas, para que actualices tu ERP sin cortes.
• Revocar invalida la credencial en menos de 60 segundos.

Buenas prácticas

• Guarda el secreto en el almacén de secretos de tu ERP o servidor, nunca en el código ni en el navegador.
• Usa una credencial distinta por sistema que se integre, para poder revocarla por separado.
• Las respuestas a recursos fuera del alcance de tu credencial son 404, igual que si no existieran.