login.dfe.public api
v4.0.0
API permettant aux consommateurs externes d'interagir avec la connexion DfE
Pour utiliser l'une des API ci-dessous, vous devrez fournir un jeton Bearer dans l'en-tête de la requête. Ce jeton Bearer est simplement un JWT (voir https://jwt.io) avec une charge utile simple qui est signée à l'aide d'un secret qui connectez-vous uniquement à DfE et vous savez.
Vous devez créer un JWT au point d'utilisation dans votre application appelante à l'aide de la bibliothèque JWT standard fournie avec la technologie que vous avez choisie.
Le corps du jeton nécessitera un émetteur (votre identifiant client de service) et une audience comme suit :
{
"iss": "REPLACE_WITH_YOUR_CLIENT_ID",
"aud": "signin.education.gov.uk"
}Le token doit être signé en utilisant l'algorithme HS256 avec votre API_SECRET. Au moment de l'intégration avec DfE Sign-in, vous auriez reçu un API_SECRET (à ne pas confondre avec votre CLIENT_SECRET), si vous ne l'avez pas, contactez l'équipe DfE Sign-in et nous en générerons un pour vous (ce sont service/environnement spécifique.)
Postman est un outil de plate-forme API utilisé pour créer et exécuter des API. Postman simplifie chaque étape du cycle de vie de l'API et est largement utilisé dans le développement et la documentation de l'API publique de connexion DfE.
Une suite de collections Postman et leurs environnements d'exécution associés ont été fournis pour vous aider à apprendre, tester et déboguer vos intégrations avec la plateforme de connexion DfE via l'API publique.
Les outils de la plateforme API Postman sont disponibles sous forme de client de bureau, d'application Web hébergée et d'interface de ligne de commande (CLI) sur https://www.postman.com/api-platform/api-client/.
La collection et les environnements Postman de l'API publique de connexion DfE sont disponibles sur https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/.
En tant que service intégré à DfE Sign-in, vous pouvez utiliser l'API pour inviter des utilisateurs au service.
La demande ressemble à
POST https://environment-url/services/{service-id}/invitations
Authorization: bearer {jwt-token}
{
"sourceId": "user_id_in_your_service",
"given_name": "John",
"family_name": "Smith",
"email": "[email protected]",
"callback": "https://me.service.url/users/signup-complete"
}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| identifiant de service | URL | Oui | L'identifiant de connexion DfE pour le service auquel vous invitez l'utilisateur à accéder |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
| identifiant source | Corps | Oui | L'identifiant de l'utilisateur dans votre système. Sera inclus dans la réponse du canal arrière |
| nom_donné | Corps | Oui | Le prénom de l'utilisateur |
| nom_famille | Corps | Oui | Le nom de famille de l'utilisateur |
| Corps | Oui | L'adresse e-mail de l'utilisateur. Il s'agit également d'un identifiant unique d'un utilisateur dans la connexion DfE. | |
| organisation | Corps | L'identifiant de connexion DfE auquel l'utilisateur doit être associé | |
| rappel | Corps | L'URL à laquelle la réponse du canal de retour doit être envoyée. Voir les détails de la réponse du canal arrière ci-dessous | |
| redirection utilisateur | Corps | L'URL vers laquelle un utilisateur, s'il effectue l'intégration, doit être renvoyé une fois l'intégration terminée. En cas d'omission, la redirection par défaut de votre client sera utilisée | |
| inviteSubjectOverride | Corps | Remplace le sujet de l'e-mail d'invitation | |
| inviteBodyOverride | Corps | Remplace le contenu de l'e-mail d'invitation |
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 202 | Votre demande a été acceptée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 401 | Votre JWT est manquant ou n'est pas valide. |
| 404 | L'ID de service dans l'URI n'existe pas |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
Lorsque la demande est faite, l'utilisateur peut exister ou non dans le système ; et peut ou non avoir les mappages d'organisation et de services souhaités demandés. Pour cette raison, tous les détails de l'utilisateur sont envoyés via une réponse du canal retour. Cela peut se produire immédiatement si l'utilisateur est trouvé (par e-mail) dans DfE Sign-in ; ou une fois que l'utilisateur aura accepté l'e-mail d'invitation qui lui sera envoyé.
La réponse du canal arrière ressemble à :
POST https://callback.url/from/request
Authorization: bearer {jwt-token}
{
"sub": "some-uuid",
"sourceId: "source-id-from-request"
}Les éléments de données de la demande sont :
| Nom | Emplacement | Description |
|---|---|---|
| jeton jwt | En-tête | Un jeton jwt, signé avec le même secret que la demande |
| sous | Corps | Identifiant de connexion DfE pour l’utilisateur. Cela ne changera pas et sera inclus dans la réponse de l'OIDC en tant que sous-réclamation. |
| identifiant source | Corps | Le sourceId utilisé dans la demande d'origine |
Les annonces peuvent être publiées et non publiées pour une organisation.
Les annonces peuvent être publiées par :
POST https://environment-url/organisations/announcements
Authorization: bearer {jwt-token}
{
"messageId": "your-unique-idenitifer",
"urn": "12345",
"type": 1,
"title": "Title of announcement",
"summary": "summary of announcement",
"body": "body of announcement",
"publishedAt": "2019-01-31T20:30:40Z",
"expiresAt": "2020-01-31T20:30:40Z"
}La structure d'une annonce est la suivante :
| Attribut | Requis | Description | Taper |
|---|---|---|---|
| ID message | Oui | Identifiant du message dans le système d'origine. Doit être unique | UUID |
| urne | Y (Ou uid) | URN de l'établissement | Numérique |
| uide | Y (Ou urne) | UID du groupe | UUID |
| taper | Oui | Le code de type numérique du message (voir ci-dessous) | Entier |
| titre | Oui | Titre de l'annonce. Limite maximale de caractères 255 | Texte ou HTML |
| résumé | Oui | Résumé de l'annonce. Nombre maximum de caractères : 340 | Texte ou HTML |
| corps | Oui | Corps de l'annonce. Nombre maximum de caractères Limite 5 000 | Texte ou HTML |
| publiéà | Oui | Annonce date/heure publiée à | ISO8601 |
| expire à | L'annonce de date/heure devrait expirer à | ISO8601 |
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 202 | Votre demande a été acceptée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 401 | Votre JWT est manquant ou n'est pas valide. |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
Les types d'annonces valides sont :
| code | signification |
|---|---|
| 1 | Avertissement concernant le dossier d'établissement |
| 2 | Problème avec le dossier d'établissement |
| 4 | Avertissement concernant le bilan de gouvernance |
| 5 | Problème avec le dossier de gouvernance |
Les annonces peuvent ensuite être dépubliées par :
DELETE https://environment-url/organisations/announcements/your-unique-idenitifer
Authorization: bearer {jwt-token} Où your-unique-idenitifer est le messageId qui a été envoyé lors de la publication du message.
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 204 | L'annonce n'a pas été publiée |
| 401 | Votre JWT est manquant ou n'est pas valide. |
| 404 | L'identifiant du message dans l'URI n'existe pas |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
Si votre application a été activée, vous pouvez créer des applications enfants via l'API. Ces applications enfants sont destinées à être utilisées lorsque vous disposez d'applications tierces qui utiliseront le flux de consentement OIDC pour leur permettre d'appeler une API au sein de votre application dans le contexte d'un utilisateur.
Les applications enfants peuvent être créées par :
POST https://environment-url/services
Authorization: bearer {jwt-token}
{
"name": "The display name of the application",
"description": "A description of what the application does",
"consentTitle": "Override for the content at the top of the Consent Screen",
"consentBody": "Override for the content of the Consent Screen",
"redirectUris": [
"https://endpoint.one/auth/cb",
"https://endpoint.two/login/callback"
]
} Remarque sur les remplacements de modèles de consentement
Deux paramètres permettent de remplacer le contenu affiché aux utilisateurs dans l'écran de consentement, le titre et le corps (tout le reste est statique selon la conception actuelle du formulaire). La valeur de remplacement est une chaîne qui comporte deux valeurs dynamiques (facultatives). Par exemple, consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"
La structure d'une candidature est la suivante :
| Attribut | Requis | Description |
|---|---|---|
| nom | Oui | Un nom convivial pour l'application. Ceci sera utilisé lors de la demande de consentement de l'utilisateur |
| description | N | Une description de la demande |
| redirectUris | Oui | Un tableau d'uris de redirection qui peuvent être utilisés pendant le flux de connexion/consentement OIDC |
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 201 | Votre application enfant a été créée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 403 | Votre application n'est pas autorisée à créer des applications enfants |
Une fois la création réussie d'une application enfant, vous recevrez une réponse telle que :
{
"name": "The display name of the application",
"description": "A description of what the application does",
"clientId": "child-application-clientid",
"clientSecret": "child-application-clientsecret",
"redirectUris": [
"https://endpoint.one/auth/cb",
"https://endpoint.two/login/callback"
]
} Le name , description et redirectUris confirment ce qui a été reçu de votre demande. Le clientId et clientSecret sont ce que l'application enfant devra utiliser lors de l'exécution des processus OIDC. Vous aurez également besoin du clientId pour toute gestion ultérieure de l'application.
Si le secret d'une application enfant est compromis, vous pouvez demander que le secret soit régénéré en :
POST https://environment-url/services/client-id-of-child-application/regenerate-secret
Authorization: bearer {jwt-token}Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 200 | Le secret a été régénéré |
| 403 | L'ID client spécifié n'est pas un enfant de votre application |
| 404 | Aucune application n'a été trouvée avec l'ID client spécifié |
Une fois la régénération réussie du secret, vous recevrez une réponse du type :
{
"clientSecret": "regenerated-client-secret"
}Les applications enfants suivent un flux de consentement explicite qui génère finalement un code d'autorisation (une subvention) qui peut être échangé contre un jeton d'accès de courte durée et un jeton d'actualisation de plus longue durée, afin de permettre aux propriétaires d'applications enfants de gérer le cycle de vie des jetons émis que nous fournissons. une API pratique pour répertorier les subventions et les problèmes symboliques pour une application enfant gouvernementale.
Ces jetons peuvent ensuite être inspectés et révoqués à l’aide des points de terminaison standard Open ID Connect (intropection et révocation).
Pour obtenir une liste des subventions pour un service à l'enfance donné :
GET https://environment-url/services/{service-id}/grantsPour obtenir une liste des jetons émis pour une subvention de service à l'enfance donnée :
GET https://environment-url/services/{service-id}/grants/{grant-id}/tokensVous pouvez utiliser cette API pour obtenir l'accès d'un utilisateur à un service pour une organisation. La demande ressemble à
GET https://environment-url/services/{service-id}/organisations/{organisation-id}/users/{user-id}
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| identifiant de service | URL | Oui | L'identifiant de connexion DfE pour le service |
| identifiant de l'organisation | URL | Oui | L'identifiant de connexion DfE pour l'organisation |
| ID de l'utilisateur | URL | Oui | L'identifiant de connexion DfE de l'utilisateur |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Cela renverra une réponse au format suivant
{
"userId": "user-id",
"serviceId": "service-id",
"organisationId": "organisation-id",
"roles": [
{
"id": "role-id",
"name": "The name of the role",
"code": "The code of the role",
"numericId": "9999",
"status": {
"id": 1
}
}
],
"identifiers": [
{
"key": "identifier-key",
"value": "identifier-value"
}
]
}Remarque : Si l'utilisateur ne dispose pas du service spécifié ou ne fait pas partie de l'organisation indiquée, il renverra le code d'état 404 (Introuvable) .
Vous pouvez utiliser cette API pour obtenir les organisations associées à un utilisateur. La requête ressemble à
GET https://environment-url/users/{user-id}/organisations
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| ID de l'utilisateur | URL | Oui | L'identifiant de connexion DfE de l'utilisateur |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Cela renverra une réponse au format suivant
[
{
"id": "org-id",
"name": "Organisation name",
"category": {
"id": "004",
"name": "Early Year Setting"
},
"urn": "org-urn",
"uid": null,
"ukprn": null,
"establishmentNumber": null,
"status": {
"id": 1,
"name": "Open"
},
"closedOn": null,
"address": null,
"telephone": null,
"statutoryLowAge": null,
"statutoryHighAge": null,
"legacyId": "legacy-id",
"companyRegistrationNumber": null
},
]Vous pouvez utiliser ce point de terminaison d'API pour obtenir les rôles associés à votre service ou à l'un de vos services enfants. La requête ressemble à :
GET https://environment-url/services/{client-id}/roles
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| identifiant client | URL | Oui | L'identifiant du client DfE Sign-in pour le service |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 200 | Une liste (éventuellement vide) de rôles a été récupérée avec succès pour l'ID client demandé. |
| 403 | L'ID client spécifié n'est pas votre service, ni un enfant de votre service. |
| 404 | Aucun service n'a été trouvé avec l'ID client spécifié. |
Cela renverra une réponse au format suivant :
[
{
"name": "Role 1 Name",
"code": "Role1Code",
"status": "Active"
},
{
"name": "Role 2 Name",
"code": "Role2Code",
"status": "Inactive"
}
]ou ce qui suit si aucun rôle n'a été trouvé :
[]
Vous pouvez utiliser cette API pour obtenir les organisations associées à un utilisateur. La requête ressemble à
GET https://environment-url/users/{user-id}/v2/organisations
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| ID de l'utilisateur | URL | Oui | L'identifiant de connexion DfE de l'utilisateur |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Cela renverra une réponse au format suivant
[
{
"id": "org-id",
"name": "Organisation name",
"category": {
"id": "001",
"name": "Establishment"
},
"urn": null,
"uid": null,
"upin": "111111",
"ukprn": "21133510",
"establishmentNumber": null,
"status": {
"id": 1,
"name": "Open"
},
"closedOn": null,
"address": "Organisation address",
"telephone": null,
"statutoryLowAge": null,
"statutoryHighAge": null,
"legacyId": "1111",
"companyRegistrationNumber": null,
"DistrictAdministrativeCode": null,
"DistrictAdministrative_code": null,
"providerTypeName": "Commercial and Charitable Provider",
"ProviderProfileID": "7777777",
"OpenedOn": null,
"SourceSystem": "PIMS",
"GIASProviderType": null,
"PIMSProviderType": "Private Limited Company",
"PIMSProviderTypeCode": 11,
"PIMSStatus": "1",
"masteringCode": null,
"PIMSStatusName": "",
"GIASStatus": null,
"GIASStatusName": null,
"MasterProviderStatusCode": 1,
"MasterProviderStatusName": "Active",
"LegalName": "Org Legal Name"
},
] Vous pouvez obtenir une liste d'utilisateurs sans filtres tels que définis dans le jeton d'autorisation (attribut iss)
La requête ressemble à :
GET https://environment-url/users?page=1&pageSize=25
Authorization: bearer {jwt-token}Les variables page et pageSize sont facultatives et par défaut respectivement 1 et 25. Ces variables permettent à l'appelant de parcourir les pages de résultats (en utilisant les attributs dans le corps de la réponse pour calculer le nombre d'enregistrements et de pages).
Le corps de la réponse contient les attributs suivants (exemple de réponse ci-dessous) :
| Nom | Description |
|---|---|
| utilisateurs | Un tableau de détails sur l'utilisateur (y compris un objet d'organisation enfant) |
| nombre d'enregistrements | Nombre total d'enregistrements signalés |
| page | Numéro de page actuel |
| nombreDePages | Nombre total de pages |
Exemple de réponse
{ "utilisateurs": [
{ "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organisation": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "name": "Département pour Éducation", "Catégorie": "002", "Type": null, "URN": null, "UID": null, "UKPRN": null, "EstablishmentNumber": "001", "Status": 1, " ClosedOn": null, "Adresse": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "telephone": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "Département du gouvernement central", "PIMSStatus": "", "DistrictAdministrativeName" : "", "Ouvert le": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Organisme gouvernemental", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019-02-20T14:27:59.020Z", "updatedAt" : "2019-02-20T14:28:38.223Z"
}, "roleName": "Approbateur", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
}
], "numberOfRecords": 1, "page": 1, "numberOfPages": 1} Vous pouvez obtenir une liste d'utilisateurs avec des filtres tels que définis dans le jeton d'autorisation (attribut iss)
La requête ressemble à :
GET https://environment-url/users?page=1&pageSize=25&status=0&from=2021%2F02%2F11%2002%3A22%3A06&to=2021%2F11%2F03%2002%3A22%3A06
Authorization: bearer {jwt-token}Les variables page et pageSize sont facultatives et par défaut respectivement 1 et 25. Ces variables permettent à l'appelant de parcourir les pages de résultats (en utilisant les attributs dans le corps de la réponse pour calculer le nombre d'enregistrements et de pages). Les statuts, de et à sont facultatifs, acceptent 0 pour le moment. la plage de dates n'accepte que 7 jours. Les dates doivent être sous forme codée en URL, comme indiqué dans l'exemple.
Validation de la plage de dates Envoyer un message d'erreur lorsque la plage de dates est supérieure à 7 jours. Seule la date de début dans le filtre permet aux utilisateurs d'être mis à jour 7 jours après la date de début. Ce n'est qu'à ce jour dans le filtre que les utilisateurs sont mis à jour 7 jours avant ce jour. Lorsqu'aucune date n'est spécifiée, les utilisateurs sont mis à jour à partir de maintenant jusqu'à 7 jours avant.
Le corps de la réponse contient les attributs suivants (exemple de réponse ci-dessous) :
| Nom | Description |
|---|---|
| utilisateurs | Un tableau de détails sur l'utilisateur (y compris un objet d'organisation enfant) |
| nombre d'enregistrements | Nombre total d'enregistrements signalés |
| page | Numéro de page actuel |
| nombreDePages | Nombre total de pages |
| avertissement (facultatif) | apparaît uniquement lors de la récupération de seulement 7 jours d'utilisateurs |
Exemple de réponse
{ "utilisateurs": [
{ "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "organisation": { "id": "13F20E54-79EA-4146 -8E39-18197576F023", "name": "Département pour Éducation", "Catégorie": "002", "Type": null, "URN": null, "UID": null, "UKPRN": null, "EstablishmentNumber": "001", "Status": 1, " ClosedOn": null, "Adresse": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "telephone": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "Département du gouvernement central", "PIMSStatus": "", "DistrictAdministrativeName" : "", "Ouvert le": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Organisme gouvernemental", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019-02-20T14:27:59.020Z", "updatedAt" : "2019-02-20T14:28:38.223Z"
}, "roleName": "Approbateur", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
}
], "numberOfRecords": 1, "page": 1, "numberOfPages": 1, "warning": "Seuls 7 jours de données peuvent être récupérés"}Pour interpréter l’identifiant de la catégorie, voir ici.
Vous pouvez obtenir une liste des approbateurs pour les organisations qui font partie de la portée de vos services (en fonction des conditions de stratégie de rôle) si votre service est autorisé à le faire.
La requête ressemble à :
GET https://environment-url/users/approvers?page=1&pageSize=25
Authorization: bearer {jwt-token}Les variables page et pageSize sont facultatives et par défaut respectivement 1 et 25. Ces variables permettent à l'appelant de parcourir les pages de résultats (en utilisant les attributs dans le corps de la réponse pour calculer le nombre d'enregistrements et de pages).
Le corps de la réponse contient les attributs suivants (exemple de réponse ci-dessous) :
| Nom | Description |
|---|---|
| utilisateurs | Un tableau de détails sur l'utilisateur (y compris un objet d'organisation enfant) |
| nombre d'enregistrements | Nombre total d'enregistrements signalés |
| page | Numéro de page actuel |
| nombreDePages | Nombre total de pages |
Exemple de réponse
Les codes de réponse possibles sont :
| Code d'état HTTP | Raison |
|---|---|
| 200 | Votre demande a été acceptée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 401 | Votre JWT est manquant ou n'est pas valide. |
| 403 | Votre candidature n'est pas autorisée à obtenir des approbateurs pour les organisations |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
{ "utilisateurs": [
{ "organisation": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "name": "Département de l'Éducation", "category": { "id": "002", "name": " Autorité locale"
}, "urn": null, "uid": null, "ukprn": null, "establishmentNumber": "001", "status": { "id": 1, "name": "Open"
}, "closedOn": null, "address": null, "telephone": null, "statutoryLowAge": null, "statutoryHighAge": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID". ": "", "UPIN": "", "PIMSProviderType": "Département du gouvernement central", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "Organisme gouvernemental", "GIASProviderType": "", "PIMSProviderTypeCode" : ""
}, "roleId": 10000, "roleName": "Approver", "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "Johnson", "givenName": "Roger"
}
], "numberOfRecords": 1, "page": 1, "numberOfPages": 1}Vous pouvez utiliser cette API pour que les utilisateurs de l'organisation filtrent par rôles. La requête ressemble à
GET https://environment-url/organisations/{UKPRN}/users?roles=role1,role2
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| UKPRN | URL | Oui | UKPRN pour l'organisation |
| rôles | URL | N | Codes de rôle utilisateur pour filtrer la liste des utilisateurs de l'organisation |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Les codes de réponse possibles incluent :
| Code d'état HTTP | Raison |
|---|---|
| 200 | Rôles récupérés avec succès pour l'organisation demandée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 401 | Votre JWT est manquant ou n'est pas valide |
| 403 | Votre application n'est pas autorisée à récupérer les utilisateurs de cette organisation |
| 404 | Aucun utilisateur n'a été trouvé avec les rôles spécifiés pour l'organisation demandée, ce qui entraîne un tableau vide |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
Cela renverra une réponse au format suivant
{
"ukprn": "organisation-ukprn-id",
"users": [
{
"email": "[email protected]",
"firstName": "user1",
"lastName": "test",
"userStatus": 1,
"roles": [
"role1"
]
},
{
"email": "[email protected]",
"firstName": "user2",
"lastName": "test",
"roles": [
"role1",
"role2"
]
}
]
}Récupérer les utilisateurs de l'organisation par critères filtrés
Vous pouvez également utiliser l'API ci-dessus pour récupérer les utilisateurs de l'organisation en fonction de critères filtrés tels que l'adresse e-mail ou l'ID utilisateur. La demande ressemble à
GET https://environment-url/organisations/{UKPRN}/[email protected]
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| UKPRN | URL | Oui | UKPRN pour l'organisation |
| URL | N | L'adresse e-mail de l'utilisateur pour le filtrage | |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Le format de réponse reste le même que celui de l'appel API précédent, permettant un filtrage selon des critères spécifiques.
Vous pouvez utiliser cette API pour que les utilisateurs de l'organisation filtrent par rôles. La requête ressemble à
GET https://environment-url/organisations/{UPIN}/users?roles=role1,role2
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| UPIN | URL | Oui | UPIN pour l'organisation |
| rôles | URL | N | Codes de rôle utilisateur pour filtrer la liste des utilisateurs de l'organisation |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Les codes de réponse possibles incluent :
| Code d'état HTTP | Raison |
|---|---|
| 200 | Rôles récupérés avec succès pour l'organisation demandée |
| 400 | Votre demande n'est pas valide. Des détails supplémentaires seront fournis dans le corps de la réponse |
| 401 | Votre JWT est manquant ou n'est pas valide |
| 403 | Votre application n'est pas autorisée à récupérer les utilisateurs de cette organisation |
| 404 | Aucun utilisateur n'a été trouvé avec les rôles spécifiés pour l'organisation demandée, ce qui entraîne un tableau vide |
| 500 | Une erreur s'est produite sur le serveur. Veuillez vous assurer que les secrets tels que les secrets, les clés API ou les jetons sont correctement configurés. Si le problème persiste, veuillez contacter l'équipe d'assistance pour obtenir de l'aide. |
Cela renverra une réponse au format suivant
{
"upin": "organisation-upin-id",
"users": [
{
"email": "[email protected]",
"firstName": "user1",
"lastName": "test",
"userStatus": 1,
"roles": [
"role1"
]
},
{
"email": "[email protected]",
"firstName": "user2",
"lastName": "test",
"roles": [
"role1",
"role2"
]
}
]
}Récupérer les utilisateurs de l'organisation par critères filtrés
Vous pouvez également utiliser l'API ci-dessus pour récupérer les utilisateurs de l'organisation en fonction de critères filtrés tels que l'adresse e-mail ou l'ID utilisateur. La demande ressemble à
GET https://environment-url/organisations/{UPIN}/[email protected]
Authorization: bearer {jwt-token}Les éléments de données variables sont :
| Nom | Emplacement | Requis | Description |
|---|---|---|---|
| UPIN | URL | Oui | UPIN pour l'organisation |
| URL | N | L'adresse e-mail de l'utilisateur pour le filtrage | |
| jeton jwt | En-tête | Oui | Le jeton JWT pour l'autorisation doit être signé à l'aide de votre secret API, qui vous sera fourni |
Le format de réponse reste le même que celui de l'appel API précédent, permettant un filtrage selon des critères spécifiques.
| identifiant | Description |
|---|---|
| 001 | Établissement (voir Types d'établissement ci-dessous) |
| 002 | Autorité locale |
| 003 | Autres organisations héritées |
| 004 | Cadre de la petite année |
| 008 | Autres parties prenantes |
| 009 | Fournisseurs de formation |
| 010 | Fiducie multi-académie |
| 011 | Gouvernement |
| 012 | Autre partie prenante du GIAS |
| 013 | Fiducie à académie unique |
| 050 | Fournisseurs de logiciels |
| 051 | Formation continue |
| identifiant | Description |
|---|---|
| 001 | École communautaire |
| 002 | École assistée par des bénévoles |
| 003 | École contrôlée volontairement |
| 005 | École de base |
| 006 | Collège technologique de la ville |
| 007 | École spéciale communautaire |
| 008 | École spéciale non entretenue |
| 010 | Autre école spéciale indépendante |
| 011 | Autre école indépendante |
| 012 | Fondation École Spéciale |
| 014 | Unité de référence des élèves |
| 015 | École maternelle de Los Angeles |
| 018 | Formation continue |
| 024 | Unités sécurisées |
| 025 | Écoles offshore |
| 026 | Service d'éducation des enfants |
| 027 | Divers |
| 028 | Dirigé par le sponsor de l’Académie |
| 029 | Établissement d'enseignement supérieur |
| 030 | Établissement gallois |
| 031 | Centres de sixième forme |
| 032 | Institution du Poste Spécial 16 |
| 033 | Sponsor spécial de l’Académie dirigé |
| 034 | Convertisseur d'académie |
| 035 | Écoles gratuites |
| 036 | Spécial écoles gratuites |
| 037 | Écoles britanniques à l'étranger |
| 038 | Écoles gratuites – Disposition alternative |
| 039 | Écoles gratuites - 16-19 ans |
| 040 | Collège pédagogique universitaire |
| 041 | Écoles-ateliers |
| 042 | Convertisseur de dispositions alternatives de l'Académie |
| 043 | Sponsor de l’offre alternative de l’Académie dirigée |
| 044 | Convertisseur spécial Académie |
| 045 | Convertisseur Académie 16-19 |
| 046 | Académie 16-19 dirigée par le sponsor |
| 047 | Enfant
Développer
Informations supplémentaires
Applications connexes
Recommandé pour vous
Actualités connexes
Tout
|
