login.dfe.public api
v4.0.0
API für externe Verbraucher zur Interaktion mit der DfE-Anmeldung
Um eine der unten aufgeführten APIs zu verwenden, müssen Sie im Header der Anfrage ein Bearer-Token angeben. Dieses Bearer-Token ist einfach ein JWT (siehe https://jwt.io) mit einer einfachen Nutzlast, die mit einem Geheimnis signiert ist Nur DfE-Anmeldung und schon wissen Sie es.
Sie sollten am Verwendungspunkt in Ihrer aufrufenden Anwendung ein JWT erstellen und dabei die Standard-JWT-Bibliothek verwenden, die mit der von Ihnen gewählten Technologie geliefert wird.
Der Token-Körper benötigt einen Aussteller (Ihre Service-Client-ID) und eine Zielgruppe wie folgt:
{
"iss": "REPLACE_WITH_YOUR_CLIENT_ID",
"aud": "signin.education.gov.uk"
}Das Token muss mit dem HS256-Algorithmus mit Ihrem API_SECRET signiert werden. Zum Zeitpunkt der Integration mit DfE Sign-in hätten Sie ein API_SECRET erhalten (nicht zu verwechseln mit Ihrem CLIENT_SECRET). Wenn Sie dieses nicht haben, wenden Sie sich an das DfE Sign-in-Team und wir werden eines für Sie neu generieren (diese sind). dienst-/umgebungsspezifisch.)
Postman ist ein API-Plattform-Tool zum Erstellen und Ausführen von APIs. Postman vereinfacht jeden Schritt des API-Lebenszyklus und wird häufig bei der Entwicklung und Dokumentation der öffentlichen API für die DfE-Anmeldung verwendet.
Es wurde eine Suite von Postman-Sammlungen und den zugehörigen Ausführungsumgebungen bereitgestellt, um Sie beim Erlernen, Testen und Debuggen Ihrer Integrationen mit der DfE-Anmeldeplattform über die öffentliche API zu unterstützen.
Die Tools der Postman API-Plattform sind als Desktop-Client, gehostete Webanwendung und Befehlszeilenschnittstelle (CLI) unter https://www.postman.com/api-platform/api-client/ verfügbar.
Die DfE Sign-in Public API Postman-Sammlung und -Umgebungen sind unter https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/ verfügbar.
Da es sich um einen in die DfE-Anmeldung integrierten Dienst handelt, können Sie die API verwenden, um Benutzer zum Dienst einzuladen.
Die Anfrage sieht aus wie
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"
}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| Dienst-ID | URL | Y | Die DfE-Anmeldekennung für den Dienst, zu dem Sie den Benutzer einladen |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
| Quellen-ID | Körper | Y | Die Kennung des Benutzers in Ihrem System. Wird in die Rückkanalantwort einbezogen |
| gegebener_name | Körper | Y | Der Vorname des Benutzers |
| Familienname | Körper | Y | Der Familienname des Benutzers |
| Körper | Y | Die E-Mail-Adresse des Benutzers. Dies ist auch eine eindeutige Kennung eines Benutzers bei der DfE-Anmeldung | |
| Organisation | Körper | Der DfE-Anmeldebezeichner, dem der Benutzer zugeordnet werden soll | |
| Rückruf | Körper | Die URL, an die die Rückkanalantwort gesendet werden soll. Einzelheiten zur Reaktion des Rückkanals finden Sie weiter unten | |
| userRedirect | Körper | Die URL, zu der ein Benutzer nach Abschluss des Onboardings zurückgeleitet werden soll. Wenn es weggelassen wird, wird die Standardumleitung für Ihren Client verwendet | |
| InvitationSubjectOverride | Körper | Überschreibt den Betreff der Einladungs-E-Mail | |
| InvitationBodyOverride | Körper | Überschreibt den Inhalt der Einladungs-E-Mail |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 202 | Ihre Anfrage wurde angenommen |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 401 | Ihr JWT fehlt oder ist ungültig. |
| 404 | Die Dienst-ID in der URL existiert nicht |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Geheimnisse, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
Wenn die Anfrage gestellt wird, kann der Benutzer im System vorhanden sein oder nicht; und möglicherweise sind die gewünschten Organisations- und Servicezuordnungen angefordert oder auch nicht. Aus diesem Grund werden alle Benutzerdaten über eine Rückkanalantwort gesendet. Dies kann entweder sofort geschehen, wenn der Benutzer (per E-Mail) in der DfE-Anmeldung gefunden wird; oder sobald der Benutzer die Einladungs-E-Mail akzeptiert, die ihm gesendet wird.
Die Antwort des Rückkanals sieht folgendermaßen aus:
POST https://callback.url/from/request
Authorization: bearer {jwt-token}
{
"sub": "some-uuid",
"sourceId: "source-id-from-request"
}Die Datenelemente in der Anfrage sind:
| Name | Standort | Beschreibung |
|---|---|---|
| JWT-Token | Kopfzeile | Ein JWT-Token, signiert mit demselben Geheimnis wie die Anfrage |
| sub | Körper | DfE-Anmelde-ID für den Benutzer. Dies ändert sich nicht und wird als Unteranspruch in die OIDC-Antwort aufgenommen |
| Quellen-ID | Körper | Die in der ursprünglichen Anfrage verwendete Quell-ID |
Ankündigungen können für eine Organisation veröffentlicht und nicht veröffentlicht werden.
Ankündigungen können veröffentlicht werden von:
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"
}Der Aufbau einer Ankündigung ist wie folgt:
| Attribut | Erforderlich | Beschreibung | Typ |
|---|---|---|---|
| Nachrichten-ID | Y | Bezeichner für die Nachricht im Ursprungssystem. Muss einzigartig sein | UUID |
| Urne | Y (oder UID) | Einrichtungs-URN | Numerisch |
| uid | Y (Oder Urne) | Gruppen-UID | UUID |
| Typ | Y | Der numerische Typcode der Nachricht (siehe unten) | Ganze Zahl |
| Titel | Y | Titel der Ankündigung. Maximale Zeichenanzahl: 255 | Text oder HTML |
| Zusammenfassung | Y | Zusammenfassung der Ankündigung. Maximale Zeichenanzahl: 340 | Text oder HTML |
| Körper | Y | Text der Ankündigung. Maximale Zeichenanzahl: 5000 | Text oder HTML |
| veröffentlichtAt | Y | Datum/Uhrzeit-Ankündigung veröffentlicht unter | ISO8601 |
| läuft ab um | Die Bekanntgabe von Datum und Uhrzeit sollte um ablaufen | ISO8601 |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 202 | Ihre Anfrage wurde angenommen |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 401 | Ihr JWT fehlt oder ist ungültig. |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Geheimnisse, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
Die gültigen Ankündigungsarten sind:
| Code | Bedeutung |
|---|---|
| 1 | Warnung vor Betriebsaufzeichnungen |
| 2 | Problem mit der Betriebsaufzeichnung |
| 4 | Warnung bezüglich der Governance-Aufzeichnung |
| 5 | Problem mit Governance-Datensatz |
Ankündigungen können nachträglich wieder rückgängig gemacht werden durch:
DELETE https://environment-url/organisations/announcements/your-unique-idenitifer
Authorization: bearer {jwt-token} Dabei ist your-unique-idenitifer die Nachrichten-ID, die beim Veröffentlichen der Nachricht gesendet wurde.
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 204 | Die Ankündigung wurde nicht veröffentlicht |
| 401 | Ihr JWT fehlt oder ist ungültig. |
| 404 | Die Nachrichten-ID in der URL existiert nicht |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Geheimnisse, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
Wenn Ihre Anwendung aktiviert wurde, können Sie über die API untergeordnete Anwendungen erstellen. Diese untergeordneten Anwendungen sind für die Verwendung gedacht, wenn Sie über Anwendungen von Drittanbietern verfügen, die den OIDC-Zustimmungsfluss verwenden, um ihnen den Aufruf einer API innerhalb Ihrer Anwendung im Kontext eines Benutzers zu ermöglichen.
Untergeordnete Anwendungen können erstellt werden durch:
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"
]
} Hinweis zu Überschreibungen von Einwilligungsvorlagen
Zwei Parameter ermöglichen das Überschreiben des Inhalts, der den Benutzern im Einwilligungsbildschirm angezeigt wird, des Titels und des Textkörpers (alles andere ist gemäß dem aktuellen Formulardesign statisch). Der Überschreibungswert ist eine Zeichenfolge mit zwei (optionalen) dynamischen Werten. z. B. consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"
Der Aufbau einer Bewerbung ist wie folgt:
| Attribut | Erforderlich | Beschreibung |
|---|---|---|
| Name | Y | Ein benutzerfreundlicher Name für die Anwendung. Dies wird verwendet, wenn der Benutzer um seine Einwilligung gebeten wird |
| Beschreibung | N | Eine Beschreibung der Anwendung |
| RedirectUris | Y | Ein Array von Umleitungs-URIS, die während des OIDC-Anmelde-/Zustimmungsablaufs verwendet werden können |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 201 | Ihre untergeordnete Anwendung wurde erstellt |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 403 | Ihre Anwendung verfügt nicht über die Berechtigung zum Erstellen untergeordneter Anwendungen |
Nach erfolgreicher Erstellung einer untergeordneten Anwendung erhalten Sie eine Antwort wie:
{
"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"
]
} Der name , description und redirectUris bestätigen, was Sie von Ihrer Anfrage erhalten haben. clientId und clientSecret müssen von der untergeordneten Anwendung verwendet werden, wenn sie OIDC-Prozesse ausführt. Sie benötigen die clientId auch für die spätere Verwaltung der Anwendung.
Wenn das Geheimnis einer untergeordneten Anwendung kompromittiert wird, können Sie die Wiederherstellung des Geheimnisses durch Folgendes anfordern:
POST https://environment-url/services/client-id-of-child-application/regenerate-secret
Authorization: bearer {jwt-token}Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 200 | Das Geheimnis wurde regeneriert |
| 403 | Die angegebene Client-ID ist kein untergeordnetes Element Ihrer Anwendung |
| 404 | Mit der angegebenen Client-ID kann keine Anwendung gefunden werden |
Nach erfolgreicher Regeneration des Geheimnisses erhalten Sie eine Antwort wie:
{
"clientSecret": "regenerated-client-secret"
}Untergeordnete Anwendungen folgen einem expliziten Zustimmungsfluss, der letztendlich einen Autorisierungscode (einen Grant) ergibt, der gegen ein kurzlebiges Zugriffstoken und ein längerlebiges Aktualisierungstoken ausgetauscht werden kann, um den Eigentümern untergeordneter Anwendungen die Verwaltung des Lebenszyklus der von uns bereitgestellten ausgegebenen Token zu ermöglichen Eine praktische API zum Auflisten von Zuschüssen und Token-Problemen für einen Antrag für ein staatliches Kind.
Diese Token können dann mithilfe der Standard-Open-ID-Connect-Endpunkte (Intropection und Revocaton) überprüft und widerrufen werden.
So erhalten Sie eine Liste der Zuschüsse für eine bestimmte Kinderbetreuung:
GET https://environment-url/services/{service-id}/grantsSo erhalten Sie eine Liste der für einen bestimmten Kindergeldzuschuss ausgestellten Token:
GET https://environment-url/services/{service-id}/grants/{grant-id}/tokensSie können diese API verwenden, um einem Benutzer Zugriff auf einen Dienst für eine Organisation zu verschaffen. Die Anfrage sieht aus wie
GET https://environment-url/services/{service-id}/organisations/{organisation-id}/users/{user-id}
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| Dienst-ID | URL | Y | Die DfE-Anmeldekennung für den Dienst |
| Organisations-ID | URL | Y | Die DfE-Anmeldekennung für die Organisation |
| Benutzer-ID | URL | Y | Die DfE-Anmeldekennung für den Benutzer |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Dadurch wird eine Antwort im folgenden Format zurückgegeben
{
"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"
}
]
}Hinweis: Wenn der Benutzer nicht über den angegebenen Dienst verfügt oder nicht zur angegebenen Organisation gehört, wird der Statuscode 404 (Nicht gefunden) zurückgegeben.
Sie können diese API verwenden, um die mit einem Benutzer verknüpften Organisationen abzurufen. Die Anfrage sieht aus
GET https://environment-url/users/{user-id}/organisations
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| Benutzer-ID | URL | Y | Die DfE-Anmeldekennung für den Benutzer |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Dadurch wird eine Antwort im folgenden Format zurückgegeben
[
{
"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
},
]Sie können diesen API-Endpunkt verwenden, um die Rollen abzurufen, die Ihrem Dienst oder einem Ihrer untergeordneten Dienste zugeordnet sind. Die Anfrage sieht so aus:
GET https://environment-url/services/{client-id}/roles
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| Client-ID | URL | Y | Die DfE-Anmelde-Client-ID für den Dienst |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 200 | Eine (möglicherweise leere) Rollenliste wurde für die angeforderte Client-ID erfolgreich abgerufen. |
| 403 | Die angegebene Client-ID ist nicht Ihr Dienst oder ein untergeordnetes Element Ihres Dienstes. |
| 404 | Mit der angegebenen Client-ID kann kein Dienst gefunden werden. |
Dadurch wird eine Antwort im folgenden Format zurückgegeben:
[
{
"name": "Role 1 Name",
"code": "Role1Code",
"status": "Active"
},
{
"name": "Role 2 Name",
"code": "Role2Code",
"status": "Inactive"
}
]oder Folgendes, wenn keine Rollen gefunden wurden:
[]
Sie können diese API verwenden, um die mit einem Benutzer verknüpften Organisationen abzurufen. Die Anfrage sieht aus
GET https://environment-url/users/{user-id}/v2/organisations
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| Benutzer-ID | URL | Y | Die DfE-Anmeldekennung für den Benutzer |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Dadurch wird eine Antwort im folgenden Format zurückgegeben
[
{
"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"
},
] Sie können eine Liste von Benutzern ohne Filter erhalten, wie im Autorisierungstoken (iss-Attribut) definiert.
Die Anfrage sieht so aus:
GET https://environment-url/users?page=1&pageSize=25
Authorization: bearer {jwt-token}Die Variablen „page“ und „pageSize“ sind optional und haben standardmäßig den Wert 1 bzw. 25. Diese Variablen ermöglichen es dem Aufrufer, über Ergebnisseiten zu iterieren (unter Verwendung von Attributen im Antworttext, um die Anzahl der Datensätze und Seiten zu berechnen).
Der Antworttext enthält die folgenden Attribute (Beispielantwort unten):
| Name | Beschreibung |
|---|---|
| Benutzer | Eine Reihe von Benutzerdetails (einschließlich eines untergeordneten Organisationsobjekts) |
| numberOfRecords | Gesamtzahl der gemeldeten Datensätze |
| Seite | Aktuelle Seitenzahl |
| numberOfPages | Gesamtzahl der Seiten |
Antwortbeispiel
{ "Benutzer": [
{ „approvedAt“: „2019-06-19T15:09:58.683Z“, „updatedAt“: „2019-06-19T15:09:58.683Z“, „organisation“: { „id“: „13F20E54-79EA-4146 -8E39-18197576F023“, „Name“: „Department for Education“, „Category“: „002“, „Type“: null, „URN“: null, „UID“: null, „UKPRN“: null, „EstablishmentNumber“: „001“, „Status“: 1, „ClosedOn“: null, „Address“: null, „phaseOfEducation“: null, „statutoryLowAge“: null, „statutoryHighAge“: null, „telephone“: null, „regionCode“: null, „legacyId“: „1031237“, „companyRegistrationNumber“: „1234567“, „ProviderProfileID“: „“, „UPIN“: „“, „PIMSProviderType“: „Central Government Department ", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": „2007-09-01T00:00:00.0000000Z“, „SourceSystem“: „“, „ProviderTypeName“: „Government Body“, „GIASProviderType“: „“, „PIMSProviderTypeCode“: „“, „createdAt“: „2019- 02-20T14:27:59.020Z“, „updatedAt“: „2019-02-20T14:28:38.223Z“
}, „roleName“: „Approver“, „roleId“: 10000, „userId“: „21D62132-6570-4E63-9DCB-137CC35E7543“, „userStatus“: 1, „email“: „[email protected]“, „familyName“: „Johnson“, „givenName“: „Roger“
}
], „numberOfRecords“: 1, „page“: 1, „numberOfPages“: 1} Sie können eine Liste von Benutzern mit Filtern erhalten, wie sie im Autorisierungstoken (iss-Attribut) definiert sind.
Die Anfrage sieht so aus:
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}Die Variablen „page“ und „pageSize“ sind optional und haben standardmäßig den Wert 1 bzw. 25. Diese Variablen ermöglichen es dem Aufrufer, über Ergebnisseiten zu iterieren (unter Verwendung von Attributen im Antworttext, um die Anzahl der Datensätze und Seiten zu berechnen). Der Status „Von“ und „Bis“ ist optional. Der Status akzeptiert derzeit 0. Der Datumsbereich akzeptiert nur 7 Tage. Datumsangaben sollten in URL-codierter Form vorliegen, wie im Beispiel gezeigt
Datumsbereichsvalidierung. Fehlermeldung senden, wenn der Datumsbereich mehr als 7 Tage beträgt. Nur das Ab-Datum im Filter sorgt dafür, dass Benutzer sieben Tage nach dem Ab-Datum aktualisiert werden. Nur „Bis-Datum“ im Filter sorgt dafür, dass Benutzer sieben Tage vor dem „Bis-Datum“ aktualisiert werden. Wenn kein Datum angegeben ist, werden Benutzer von jetzt an auf 7 Tage davor aktualisiert.
Der Antworttext enthält die folgenden Attribute (Beispielantwort unten):
| Name | Beschreibung |
|---|---|
| Benutzer | Eine Reihe von Benutzerdetails (einschließlich eines untergeordneten Organisationsobjekts) |
| numberOfRecords | Gesamtzahl der gemeldeten Datensätze |
| Seite | Aktuelle Seitenzahl |
| numberOfPages | Gesamtzahl der Seiten |
| Warnung (optional) | erscheint nur, wenn nur 7 Tage Benutzer abgerufen werden |
Antwortbeispiel
{ "Benutzer": [
{ „approvedAt“: „2019-06-19T15:09:58.683Z“, „updatedAt“: „2019-06-19T15:09:58.683Z“, „organisation“: { „id“: „13F20E54-79EA-4146 -8E39-18197576F023“, „Name“: „Department for Education“, „Category“: „002“, „Type“: null, „URN“: null, „UID“: null, „UKPRN“: null, „EstablishmentNumber“: „001“, „Status“: 1, „ClosedOn“: null, „Address“: null, „phaseOfEducation“: null, „statutoryLowAge“: null, „statutoryHighAge“: null, „telephone“: null, „regionCode“: null, „legacyId“: „1031237“, „companyRegistrationNumber“: „1234567“, „ProviderProfileID“: „“, „UPIN“: „“, „PIMSProviderType“: „Central Government Department ", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": „2007-09-01T00:00:00.0000000Z“, „SourceSystem“: „“, „ProviderTypeName“: „Government Body“, „GIASProviderType“: „“, „PIMSProviderTypeCode“: „“, „createdAt“: „2019- 02-20T14:27:59.020Z“, „updatedAt“: „2019-02-20T14:28:38.223Z“
}, „roleName“: „Approver“, „roleId“: 10000, „userId“: „21D62132-6570-4E63-9DCB-137CC35E7543“, „userStatus“: 1, „email“: „[email protected]“, „familyName“: „Johnson“, „givenName“: „Roger“
}
], „numberOfRecords“: 1, „page“: 1, „numberOfPages“: 1, „warning“: „Nur 7 Tage Daten können abgerufen werden“}Informationen zur Interpretation der Kategorie-ID finden Sie hier.
Sie können eine Liste der Genehmiger für Organisationen abrufen, die in Ihrem Servicebereich liegen (basierend auf Rollenrichtlinienbedingungen), wenn Ihr Service dazu berechtigt ist.
Die Anfrage sieht so aus:
GET https://environment-url/users/approvers?page=1&pageSize=25
Authorization: bearer {jwt-token}Die Variablen „page“ und „pageSize“ sind optional und haben standardmäßig den Wert 1 bzw. 25. Diese Variablen ermöglichen es dem Aufrufer, über Ergebnisseiten zu iterieren (unter Verwendung von Attributen im Antworttext, um die Anzahl der Datensätze und Seiten zu berechnen).
Der Antworttext enthält die folgenden Attribute (Beispielantwort unten):
| Name | Beschreibung |
|---|---|
| Benutzer | Eine Reihe von Benutzerdetails (einschließlich eines untergeordneten Organisationsobjekts) |
| numberOfRecords | Gesamtzahl der gemeldeten Datensätze |
| Seite | Aktuelle Seitenzahl |
| numberOfPages | Gesamtzahl der Seiten |
Antwortbeispiel
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 200 | Ihre Anfrage wurde angenommen |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 401 | Ihr JWT fehlt oder ist ungültig. |
| 403 | Ihre Anwendung verfügt nicht über die Berechtigung, Genehmiger für Organisationen zu erhalten |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Secrets, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
{ "Benutzer": [
{ "organisation": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "name": "Department for Education", "category": { "id": "002", "name": " Lokale Behörde“
}, „urn“: null, „uid“: null, „ukprn“: null, „establishmentNumber“: „001“, „status“: { „id“: 1, „name“: „Offen“
}, „closedOn“: null, „address“: null, „telephone“: null, „statutoryLowAge“: null, „statutoryHighAge“: null, „legacyId“: „1031237“, „companyRegistrationNumber“: „1234567“, „ProviderProfileID „: „“, „UPIN“: „“, „PIMSProviderType“: „Zentrale Regierungsabteilung“, „PIMSStatus“: „“, „DistrictAdministrativeName“: „“, „OpenedOn“: „2007-09-01T00:00:00.0000000Z“, „SourceSystem“: „“, „ProviderTypeName“: „Government Body“, „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}Sie können diese API verwenden, um die Benutzer der Organisation nach Rollen zu filtern. Die Anfrage sieht so aus
GET https://environment-url/organisations/{UKPRN}/users?roles=role1,role2
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| UKPRN | URL | Y | UKPRN für die Organisation |
| Rollen | URL | N | Benutzerrollencodes zum Filtern der Benutzerliste der Organisation |
| JWT-Token | Kopfzeile | Y | Das JWT-Token zur Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 200 | Rollen für die angeforderte Organisation erfolgreich abgerufen |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 401 | Ihr JWT fehlt oder ist ungültig |
| 403 | Ihrer Anwendung fehlt die Berechtigung zum Abrufen von Benutzern für diese Organisation |
| 404 | Für die angeforderte Organisation wurden keine Benutzer mit den angegebenen Rollen gefunden, was zu einem leeren Array führt |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Geheimnisse, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
Dadurch wird eine Antwort im folgenden Format zurückgegeben
{
"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"
]
}
]
}Rufen Sie Organisationsbenutzer nach gefilterten Kriterien ab
Sie können die obige API auch verwenden, um Organisationsbenutzer basierend auf gefilterten Kriterien wie E-Mail-Adresse oder Benutzer-ID abzurufen. Die Anfrage sieht aus wie
GET https://environment-url/organisations/{UKPRN}/[email protected]
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| UKPRN | URL | Y | UKPRN für die Organisation |
| URL | N | Die E-Mail-Adresse des Benutzers zum Filtern | |
| JWT-Token | Kopfzeile | Y | Das JWT-Token für die Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Das Antwortformat bleibt das gleiche wie beim vorherigen API-Aufruf und ermöglicht die Filterung nach bestimmten Kriterien.
Sie können diese API verwenden, um die Benutzer der Organisation nach Rollen zu filtern. Die Anfrage sieht so aus
GET https://environment-url/organisations/{UPIN}/users?roles=role1,role2
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| UPIN | URL | Y | UPIN für die Organisation |
| Rollen | URL | N | Benutzerrollencodes zum Filtern der Benutzerliste der Organisation |
| JWT-Token | Kopfzeile | Y | Das JWT-Token für die Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Mögliche Antwortcodes sind:
| HTTP-Statuscode | Grund |
|---|---|
| 200 | Rollen für die angeforderte Organisation erfolgreich abgerufen |
| 400 | Ihre Anfrage ist ungültig. Weitere Details werden im Antworttext bereitgestellt |
| 401 | Ihr JWT fehlt oder ist ungültig |
| 403 | Ihrer Anwendung fehlt die Berechtigung zum Abrufen von Benutzern für diese Organisation |
| 404 | Für die angeforderte Organisation wurden keine Benutzer mit den angegebenen Rollen gefunden, was zu einem leeren Array führt |
| 500 | Auf dem Server ist ein Fehler aufgetreten. Bitte stellen Sie sicher, dass Geheimnisse wie Geheimnisse, API-Schlüssel oder Token korrekt konfiguriert sind. Wenn das Problem weiterhin besteht, wenden Sie sich bitte an das Support-Team, um Hilfe zu erhalten |
Dadurch wird eine Antwort im folgenden Format zurückgegeben
{
"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"
]
}
]
}Rufen Sie Organisationsbenutzer nach gefilterten Kriterien ab
Sie können die obige API auch verwenden, um Organisationsbenutzer basierend auf gefilterten Kriterien wie E-Mail-Adresse oder Benutzer-ID abzurufen. Die Anfrage sieht aus wie
GET https://environment-url/organisations/{UPIN}/[email protected]
Authorization: bearer {jwt-token}Die variablen Datenelemente sind:
| Name | Standort | Erforderlich | Beschreibung |
|---|---|---|---|
| UPIN | URL | Y | UPIN für die Organisation |
| URL | N | Die E-Mail-Adresse des Benutzers zum Filtern | |
| JWT-Token | Kopfzeile | Y | Das JWT-Token für die Autorisierung sollte mit Ihrem API-Geheimnis signiert werden, das Ihnen zur Verfügung gestellt wird |
Das Antwortformat bleibt das gleiche wie beim vorherigen API-Aufruf und ermöglicht die Filterung nach bestimmten Kriterien.
| Ausweis | Beschreibung |
|---|---|
| 001 | Betriebsstätte (siehe Betriebstypen unten) |
| 002 | Lokale Behörde |
| 003 | Andere Legacy-Organisationen |
| 004 | Frühe Jahreseinstellung |
| 008 | Andere Stakeholder |
| 009 | Schulungsanbieter |
| 010 | Multi-Academy Trust |
| 011 | Regierung |
| 012 | Andere GIAS-Stakeholder |
| 013 | Single-Academy Trust |
| 050 | Softwarelieferanten |
| 051 | Weiterbildung |
| Ausweis | Beschreibung |
|---|---|
| 001 | Gemeinschaftsschule |
| 002 | Freiwillige unterstützte Schule |
| 003 | Freiwillige kontrollierte Schule |
| 005 | Stiftungsschule |
| 006 | Städtisches Technologie-College |
| 007 | Gemeinschaftliche Sonderschule |
| 008 | Nicht unterhaltene Sonderschule |
| 010 | Andere unabhängige Sonderschule |
| 011 | Andere unabhängige Schule |
| 012 | Fondation Sonderschule |
| 014 | Referat für Schülervermittlung |
| 015 | LA Kindergarten |
| 018 | Weiterbildung |
| 024 | Sichere Einheiten |
| 025 | Offshore-Schulen |
| 026 | Service Kindererziehung |
| 027 | Verschiedenes |
| 028 | Akademie-Sponsor geleitet |
| 029 | Hochschule |
| 030 | Walisisches Establishment |
| 031 | Zentren der sechsten Klasse |
| 032 | Sonderposten 16 Institution |
| 033 | Akademie-Sondersponsor geleitet |
| 034 | Akademie-Konverter |
| 035 | Freie Schulen |
| 036 | Kostenloses Schulangebot |
| 037 | Britische Überseeschulen |
| 038 | Freie Schulen – Alternative Angebote |
| 039 | Freie Schulen – 16-19 |
| 040 | Pädagogische Hochschule der Universität |
| 041 | Studioschulen |
| 042 | Academy Alternative Provision Converter |
| 043 | Sponsor der Akademie für alternative Angebote |
| 044 | Akademie-Spezialkonverter |
| 045 | Academy 16-19 Konverter |
| 046 | Academy 16-19 Sponsor geführt |
| 047 | Kinder
Expandieren
Zusätzliche Informationen
Ähnliche Anwendungen
Empfohlen für Sie
Ähnliche Nachrichten
Alle
|
