Authentication

Reconstructed from API key points.

Single endpoint:

https://{client-subdomain}.ublo.immo/api/graphql

Two authentication modes are available:

Mode	Lifetime	Typical use
Session cookie (UBLO_TOKEN_AUTHENTICATION)	~7 days	Scripts, curl trials, token generation
API token (Authorization: Bearer …)	No expiry (revocable)	Long-lived server integrations

Never expose the session or token in a public browser

Keep cookies.txt / the Bearer token only in your backend, worker, or CI.

Step 1 — Open a session (login)

The login mutation creates the UBLO_TOKEN_AUTHENTICATION cookie. Prefer a collaborator attached to the parent company (otherwise you may hit BU-related unauthorized).

With curl, persist the cookie jar with -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 holds UBLO_TOKEN_AUTHENTICATION — send it back on later calls

curl

# -c cookies.txt: write the session cookie (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"
    }
  }'

curl option	Role
-c cookies.txt	Write the cookie jar after the response (Set-Cookie)
-b cookies.txt	Send the jar on subsequent requests

Option A — Call the API with the session cookie

Once cookies.txt exists, reuse it on every query / mutation with -b (no Bearer):

# -b cookies.txt: send the session opened at 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 } }"}'

Equivalent Node.js (Cookie header):

const cookieHeader = /* UBLO_TOKEN_AUTHENTICATION value from login */;

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

Logout

Call the logout mutation (still with -b cookies.txt) to invalidate the session, then delete the jar file.

Option B — Generate an API token (Bearer)

For long-lived integrations: generate a token after login (cookie required), then authenticate with Authorization: Bearer ….

The mutation returns an ApiTokenResponse: the token is in success; on failure, use error.

GraphQL

mutation {
  generateApiToken {
    success
    error
  }
}

Node.js

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

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

curl

# Session cookie is required here (-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 } }"}'

Related schema ops: apiTokens, revokeToken.

Subsequent Bearer calls

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}`,
}

Every cookbook curl tab offers Bearer and Cookie session variants. The Node helper accepts UBLO_API_TOKEN or UBLO_COOKIE.

Next

• Minimal HTTP client
• Conventions