Authentification

Reconstruit d’après Points clés de l’API.

L’endpoint unique :

https://{TENANT}.ublo.immo/api/graphql

Deux modes d’authentification sont possibles :

Mode	Durée	Usage typique
Cookie de session (UBLO_TOKEN_AUTHENTICATION)	~7 jours	Scripts, essais curl, génération de token
Token API (Authorization: Bearer …)	Sans expiration (révocable)	Intégrations serveur durables

Ne jamais exposer session ou token côté navigateur public

Conservez cookies.txt / le Bearer uniquement dans votre backend, worker ou CI.

Étape 1 — Ouvrir une session (login)

La mutation login crée le cookie UBLO_TOKEN_AUTHENTICATION. Le profil collaborateur doit idéalement être rattaché à la société mère (sinon risque d’unauthorized lié aux Business Units).

Avec curl, enregistrez le cookie dans un cookie jar avec -c :

GraphQL

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password)
}

{
  "email": "[email protected]",
  "password": "••••••••"
}

Node.js

const ENDPOINT = 'https://example.ublo.immo/api/graphql';

async function gql(query, variables, { token, cookieJar } = {}) {
  const headers = {
    'Content-Type': 'application/json',
    Accept: 'application/json',
  };
  if (token) headers.Authorization = `Bearer ${token}`;
  if (cookieJar) headers.Cookie = cookieJar;

  const res = await fetch(ENDPOINT, {
    method: 'POST',
    headers,
    body: JSON.stringify({ query, variables }),
  });

  const setCookie = res.headers.getSetCookie?.() ?? [];
  const json = await res.json();
  if (json.errors?.length) {
    const err = new Error(json.errors.map((e) => e.message).join('; '));
    err.graphQLErrors = json.errors;
    throw err;
  }
  return { data: json.data, setCookie };
}

const { data, setCookie } = await gql(
  `mutation Login($email: String!, $password: String!) {
    login(email: $email, password: $password)
  }`,
  { email: process.env.UBLO_EMAIL, password: process.env.UBLO_PASSWORD },
);

console.log('login ok', Boolean(data.login));
// setCookie contient UBLO_TOKEN_AUTHENTICATION — à renvoyer ensuite

curl

# -c cookies.txt : écrit le cookie de session (UBLO_TOKEN_AUTHENTICATION)
curl -sS -X POST 'https://example.ublo.immo/api/graphql' \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{
    "query": "mutation Login($email: String!, $password: String!) { login(email: $email, password: $password) }",
    "variables": {
      "email": "[email protected]",
      "password": "YOUR_PASSWORD"
    }
  }'

Option curl	Rôle
-c cookies.txt	Écrit le jar de cookies après la réponse (Set-Cookie)
-b cookies.txt	Envoie le jar sur les appels suivants

Option A — Appeler l’API avec le cookie de session

Une fois cookies.txt créé, réutilisez-le sur toutes les queries / mutations avec -b (sans Bearer) :

# -b cookies.txt : envoie la session ouverte au login
curl -sS -X POST 'https://example.ublo.immo/api/graphql' \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"query":"query { company { id name } }"}'

Exemple Node.js équivalent (en-tête Cookie) :

const cookieHeader = /* valeur de UBLO_TOKEN_AUTHENTICATION extraite du login */;

const { data } = await gql(
  `query { company { id name } }`,
  undefined,
  { cookieJar: cookieHeader },
);

Déconnexion

Utilisez la mutation logout (toujours avec -b cookies.txt) pour invalider la session, puis supprimez le fichier jar.

Option B — Générer un token API (Bearer)

Pour une intégration longue durée : générez un token après le login (cookie requis), puis authentifiez les appels avec Authorization: Bearer ….

La mutation renvoie un ApiTokenResponse : le jeton est dans success ; en cas d’échec, utilisez error.

GraphQL

mutation {
  generateApiToken {
    success
    error
  }
}

Node.js

const { data } = await gql(
  `mutation { generateApiToken { success error } }`,
  undefined,
  { cookieJar: /* cookies de login */ undefined },
);

if (data.generateApiToken.error) {
  throw new Error(data.generateApiToken.error);
}
process.env.UBLO_API_TOKEN = data.generateApiToken.success;

curl

# La session cookie est obligatoire ici (-b cookies.txt)
curl -sS -X POST 'https://example.ublo.immo/api/graphql' \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"query":"mutation { generateApiToken { success error } }"}'

Opérations associées dans le schéma : apiTokens, revokeToken.

Appels suivants en Bearer

curl -sS -X POST 'https://example.ublo.immo/api/graphql' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $UBLO_API_TOKEN" \
  -d '{"query":"query { company { id name } }"}'

headers: {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.UBLO_API_TOKEN}`,
}

Chaque onglet curl du cookbook propose les variantes Bearer et Cookie session. Le helper Node accepte UBLO_API_TOKEN ou UBLO_COOKIE.

Suite

• Client HTTP minimal
• Conventions