PATCH/v1/apps/{app_id}

Modifier une application OAuth

update_app

Modifie les champs que vous transmettez. Restreindre scopes restreint immédiatement les jetons déjà émis ; un élargissement ne s’applique qu’aux nouvelles autorisations. role et data_profile ne s’appliquent qu’à une application confidential. Le type de client ne peut pas être modifié. Ajouté dans la version 1.62.0.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

app_idstringobligatoire
ID de l’application (app_…), qui est aussi le client_id.
length ≤ 36

Paramètres d’en-tête

Idempotency-Keystring
Clé permettant de réessayer une écriture sans risque : de 1 à 255 caractères ASCII imprimables ; un UUID v4 par opération logique est recommandé. Une nouvelle tentative avec la même clé dans les 24 heures n’exécute pas l’opération une seconde fois : elle renvoie la réponse enregistrée (statut, en-têtes et corps) avec l’en-tête Idempotency-Replayed: true. La même clé avec une méthode, un chemin, un Content-Type ou un corps différents renvoie 409 api.idempotency_mismatch ; tant que la première requête est en cours, 409 api.idempotency_in_progress avec Retry-After: 1. Après une réponse 5xx ou 429, la clé est libérée, et une nouvelle tentative exécute de nouveau l’opération. La clé est propre à l’organisation et à l’appelant (clé API, utilisateur ou clé de source personnalisée).
length ≥ 1, length ≤ 255

Corps de la requête

application/json

Objet : OAuthAppUpdate

namestring
Nom pour l’écran de consentement.
length ≥ 1, length ≤ 100
descriptionstring
Description pour l’écran de consentement.
length ≤ 1000
homepage_urlstring | null
Site web de l’application ; null ou une chaîne vide le supprime.
length ≤ 2000
redirect_urisarray of string
Nouvelle liste complète des URI de redirection.
items ≤ 10
scopesarray of OAuthScope
Nouvel ensemble complet de portées.
items ≥ 1
rolestring
Rôle des jetons d’identifiants client (confidential uniquement).
data_profilestring
Profil de données des jetons d’identifiants client (confidential uniquement).

Réponses

200Réponse réussie

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.
Idempotency-Replayed
true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : OAuthApp

idstringobligatoire
ID de l’application (app_ et 32 caractères hexadécimaux), qui sert aussi de client_id.
namestringobligatoire
Nom qu’un salarié voit sur l’écran de consentement.
descriptionstringobligatoire
Description pour l’écran de consentement (peut être vide).
homepage_urlstring | nullobligatoire
Site web de l’application.
client_typeOAuthClientTypeobligatoire
redirect_urisarray of stringobligatoire
URI de redirection autorisées (correspondance exacte de la chaîne).
scopesarray of OAuthScopeobligatoire
Portées que l’application peut demander.
client_secret_prefixstring | nullobligatoire
Premiers caractères du secret client, pour le reconnaître ; null pour une application publique.
rolestring | nullobligatoire
Rôle des jetons d’identifiants client (admin, editor, verifier, viewer) ; null pour une application publique.
data_profilestring | nullobligatoire
Profil de données des jetons d’identifiants client ; null pour une application publique.
authorizationsintegerobligatoire
Nombre d’autorisations actives de salariés.
created_atstring (date-time)obligatoire
updated_atstring (date-time)obligatoire

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

409L’état de l’objet ne permet pas l’action, par exemple un doublon, une indexation en cours ou un job déjà traité.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← apps · Référence de l’API

curl -X PATCH 'https://api.sursa.com/v1/apps/APP_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"support","description":"Customer support articles","homepage_url":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

app_id path *

Idempotency-Key header

Idempotency-Key

Si ce champ est vide, une nouvelle clé est générée pour chaque requête.

Corps de la requête (JSON)