Droits et visibilité

Chaque appel agit au nom d'un utilisateur, avec ses droits : une liste ne rend que les fiches qu'il voit, et une route refuse ce qu'il n'a pas le droit de faire (403).

Les niveaux

Un droit donne un niveau sur une fiche à un utilisateur, à une organisation ou à un cercle (un groupe d'utilisateurs et d'organisations) :

Le droit qui s'applique

Plusieurs droits peuvent concerner le même utilisateur : le sien, celui de son organisation, ceux des cercles (actifs) dont lui ou son organisation est membre. Celui de plus petite priorité (Priority) l'emporte. Un droit « Aucun » placé au-dessus des autres retire donc la fiche à un utilisateur, même si son organisation la voit.

Lire et poser les droits

• GET https://staging-api.docage.com/Rights/EntityList/{entityid}/{entityTypeName} : les droits posés sur une fiche (entityTypeName est le type technique de la fiche : Contact, Transaction…).
• GET https://staging-api.docage.com/Rights/DefaultRights/{entityTypeName} : les droits qu'une fiche neuve de ce type recevra, d'après les réglages de l'organisation et de l'utilisateur.
• POST https://staging-api.docage.com/Rights : poser un droit, réservé à qui administre la fiche.

Un entityTypeName (ou un EntityTypeName) qui n'est pas le nom technique d'un type de fiche répond 400 ; une fiche introuvable, ou que vous ne voyez pas, 404.

POST https://staging-api.docage.com/Rights
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "EntityId": "9b2d7a46-3c1e-4f0a-8b5d-1a2b3c4d5e6f",
  "EntityTypeName": "Contact",
  "SecurityEntityId": "7e8f9a0b-0000-4000-8000-000000000077",
  "SecurityEntityTypeName": "Circle",
  "RightLevel": 2,
  "Priority": 10
}

curl -X POST "https://staging-api.docage.com/Rights" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "EntityId": "9b2d7a46-3c1e-4f0a-8b5d-1a2b3c4d5e6f",
    "EntityTypeName": "Contact",
    "SecurityEntityId": "7e8f9a0b-0000-4000-8000-000000000077",
    "SecurityEntityTypeName": "Circle",
    "RightLevel": 2,
    "Priority": 10
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Rights");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "EntityId": "9b2d7a46-3c1e-4f0a-8b5d-1a2b3c4d5e6f",
      "EntityTypeName": "Contact",
      "SecurityEntityId": "7e8f9a0b-0000-4000-8000-000000000077",
      "SecurityEntityTypeName": "Circle",
      "RightLevel": 2,
      "Priority": 10
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Rights", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "EntityId": "9b2d7a46-3c1e-4f0a-8b5d-1a2b3c4d5e6f",
    "EntityTypeName": "Contact",
    "SecurityEntityId": "7e8f9a0b-0000-4000-8000-000000000077",
    "SecurityEntityTypeName": "Circle",
    "RightLevel": 2,
    "Priority": 10
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

SecurityEntityTypeName désigne qui reçoit le droit : DocageUser (un utilisateur), Organization ou Circle.

Ce qu'il faut savoir

• Une liste omet une fiche que l'utilisateur ne voit pas ; la lire par son identifiant (GET https://staging-api.docage.com/Contacts/{id}) répond 200 et null, comme pour une fiche qui n'existe pas. C'est une mesure de sécurité : la réponse ne révèle pas qu'une fiche existe à qui ne la voit pas.
• Une société désignée par une écriture — ParentCompanyId d'un contact ou d'un groupe, CompanyId d'une carte, d'un événement ou d'un appel, une société liée ajoutée à un groupe — doit être une société que l'utilisateur voit. Sinon la création ou la modification répond 422, avec le même message pour une société qu'il ne voit pas et pour une société qui n'existe pas. Une société déjà posée, que la modification ne change pas, n'est pas contrôlée.
• Les droits d'une fiche neuve se posent d'office, selon les réglages de son organisation. Un administrateur peut les donner dès la création, dans ParentRightsDTO.
• Un utilisateur de l'organisation intégratrice agit chez une cliente selon les droits qu'il y a — voir Organisations et intégrateurs.