login.dfe.public api
v4.0.0
외부 소비자가 DfE 로그인과 상호작용하기 위한 API
아래 API 중 하나를 사용하려면 요청 헤더에 Bearer 토큰을 제공해야 합니다. 이 Bearer 토큰은 다음과 같은 비밀을 사용하여 서명된 간단한 페이로드가 있는 JWT(https://jwt.io 참조)입니다. DfE 로그인만 하면 알 수 있습니다.
선택한 기술과 함께 제공되는 표준 JWT 라이브러리를 사용하여 호출 애플리케이션에서 사용 시점에 JWT를 생성해야 합니다.
토큰 본문에는 다음과 같이 발급자(서비스 클라이언트 ID)와 대상이 필요합니다.
{
"iss": "REPLACE_WITH_YOUR_CLIENT_ID",
"aud": "signin.education.gov.uk"
}토큰은 API_SECRET과 함께 HS256 알고리즘을 사용하여 서명되어야 합니다. DfE 로그인과의 통합 시점에 API_SECRET(CLIENT_SECRET과 혼동하지 않도록)이 제공되었을 것입니다. API_SECRET이 없는 경우 DfE 로그인 팀에 문의하시면 다시 생성해 드리겠습니다(이것은 서비스/환경에 따라 다릅니다.)
Postman은 API를 구축하고 실행하는 데 사용되는 API 플랫폼 도구입니다. Postman은 API 수명 주기의 각 단계를 단순화하고 DfE 로그인 공개 API의 개발 및 문서화에 광범위하게 사용됩니다.
공개 API를 통해 DfE 로그인 플랫폼과의 통합을 학습, 테스트 및 디버깅하는 데 도움이 되는 일련의 Postman 컬렉션 및 관련 실행 환경이 제공되었습니다.
Postman API 플랫폼 도구는 https://www.postman.com/api-platform/api-client/에서 데스크톱 클라이언트, 호스팅된 웹 애플리케이션 및 명령줄 인터페이스(CLI)로 사용할 수 있습니다.
DfE 로그인 공개 API Postman 컬렉션 및 환경은 https://github.com/DFE-Digital/login.dfe.public-api/tree/develop/Postman/에서 사용할 수 있습니다.
DfE 로그인에 탑재된 서비스로서 API를 사용하여 사용자를 서비스에 초대할 수 있습니다.
요청은 다음과 같습니다
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"
}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 서비스 ID | URL | 와이 | 사용자를 초대하려는 서비스의 DfE 로그인 식별자 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
| 소스 ID | 몸 | 와이 | 시스템에 있는 사용자의 식별자입니다. 백채널 응답에 포함됩니다. |
| 주어진_이름 | 몸 | 와이 | 사용자 이름 |
| family_name | 몸 | 와이 | 사용자 성 |
| 이메일 | 몸 | 와이 | 사용자의 이메일 주소입니다. 이는 DfE 로그인에서 사용자의 고유 식별자이기도 합니다. |
| 조직 | 몸 | 사용자와 연결되어야 하는 DfE 로그인 식별자 | |
| 콜백 | 몸 | 백 채널 응답을 보내야 하는 URL입니다. 아래에서 백 채널 응답에 대한 자세한 내용을 확인하세요. | |
| 사용자리디렉션 | 몸 | 사용자가 온보딩을 진행하는 경우 완료 시 반환되어야 하는 URL입니다. 생략하면 클라이언트의 기본 리디렉션이 사용됩니다. | |
| InvitationSubjectOverride | 몸 | 초대 이메일의 제목을 재정의합니다. | |
| InvitationBodyOverride | 몸 | 초대 이메일의 내용을 재정의합니다. |
가능한 응답 코드는 다음과 같습니다.
| HTTP 상태 코드 | 이유 |
|---|---|
| 202 | 귀하의 요청이 승인되었습니다 |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 404 | URI의 서비스 ID가 존재하지 않습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
요청이 이루어지면 사용자가 시스템에 존재할 수도 있고 존재하지 않을 수도 있습니다. 원하는 조직 및 서비스 매핑이 요청될 수도 있고 그렇지 않을 수도 있습니다. 이러한 이유로 모든 사용자 세부 정보는 백 채널 응답을 통해 전송됩니다. 이는 DfE 로그인에서 사용자가 이메일을 통해 발견된 경우 즉시 발생할 수 있습니다. 또는 사용자가 전송될 초대 이메일을 수락하면 가능합니다.
백 채널 응답은 다음과 같습니다.
POST https://callback.url/from/request
Authorization: bearer {jwt-token}
{
"sub": "some-uuid",
"sourceId: "source-id-from-request"
}요청의 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 설명 |
|---|---|---|
| jwt 토큰 | 헤더 | 요청과 동일한 비밀로 서명된 JWT 토큰 |
| 보결 | 몸 | 사용자의 DfE 로그인 식별자입니다. 이는 변경되지 않으며 OIDC 응답에 하위 청구로 포함됩니다. |
| 소스 ID | 몸 | 원래 요청에 사용된 sourceId |
공지 사항은 조직에 게시되거나 게시 취소될 수 있습니다.
공지 사항은 다음을 통해 게시할 수 있습니다.
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"
}공지사항의 구조는 다음과 같습니다.
| 기인하다 | 필수의 | 설명 | 유형 |
|---|---|---|---|
| 메시지 ID | 와이 | 원본 시스템의 메시지 식별자입니다. 고유해야 합니다. | UUID |
| 항아리 | Y(또는 uid) | 설립 URN | 숫자 |
| UID | Y (또는 항아리) | 그룹 UID | UUID |
| 유형 | 와이 | 메시지의 숫자 유형 코드(아래 참조) | 정수 |
| 제목 | 와이 | 공지사항의 제목입니다. 최대 문자 수 제한은 255자입니다. | 텍스트 또는 HTML |
| 요약 | 와이 | 공지사항 요약입니다. 최대 문자 수 제한 340 | 텍스트 또는 HTML |
| 몸 | 와이 | 공지사항의 본문입니다. 최대 문자 수 제한 5000 | 텍스트 또는 HTML |
| 게시 시간 | 와이 | 게시된 날짜/시간 공지사항 | ISO8601 |
| 만료일 | 날짜/시간 공지는 에 만료되어야 합니다. | ISO8601 |
가능한 응답 코드는 다음과 같습니다:
| HTTP 상태 코드 | 이유 |
|---|---|
| 202 | 귀하의 요청이 승인되었습니다 |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
유효한 공지 유형은 다음과 같습니다.
| 암호 | 의미 |
|---|---|
| 1 | 설립기록에 관한 경고 |
| 2 | 설립기록 문제 |
| 4 | 거버넌스 기록에 대한 경고 |
| 5 | 거버넌스 기록 문제 |
공지사항은 이후에 다음 방법으로 게시를 취소할 수 있습니다.
DELETE https://environment-url/organisations/announcements/your-unique-idenitifer
Authorization: bearer {jwt-token} your-unique-idenitifer 메시지를 게시할 때 전송된 messageId입니다.
가능한 응답 코드는 다음과 같습니다.
| HTTP 상태 코드 | 이유 |
|---|---|
| 204 | 공지사항이 게시 취소되었습니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 404 | URI의 메시지 ID가 존재하지 않습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
애플리케이션이 활성화된 경우 API를 통해 하위 애플리케이션을 생성할 수 있습니다. 이러한 하위 애플리케이션은 사용자 컨텍스트에서 애플리케이션 내에서 API를 호출할 수 있도록 OIDC 동의 흐름을 사용하는 타사 애플리케이션이 있는 경우에 사용하기 위한 것입니다.
하위 애플리케이션은 다음을 통해 생성할 수 있습니다.
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"
]
} 동의 템플릿 재정의에 대한 참고 사항
두 개의 매개변수를 사용하면 동의 화면에서 사용자에게 표시되는 콘텐츠, 제목 및 본문을 재정의할 수 있습니다(다른 모든 항목은 현재 양식 디자인에 따라 정적입니다). 재정의 값은 두 개의(선택 사항) 동적 값이 있는 문자열입니다. 예: consentTitle="Do you want to allow {{applicationName}} to send data to us for {{roleScope}}"
애플리케이션의 구조는 다음과 같습니다.
| 기인하다 | 필수의 | 설명 |
|---|---|---|
| 이름 | 와이 | 애플리케이션의 사용자 친화적인 이름입니다. 사용자에게 동의를 요청할 때 사용됩니다. |
| 설명 | N | 애플리케이션에 대한 설명 |
| 리디렉션Uris | 와이 | OIDC 로그인/동의 흐름 중에 사용할 수 있는 리디렉션 URI 배열입니다. |
가능한 응답 코드는 다음과 같습니다:
| HTTP 상태 코드 | 이유 |
|---|---|
| 201 | 귀하의 하위 애플리케이션이 생성되었습니다 |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 403 | 귀하의 애플리케이션에는 하위 애플리케이션을 생성할 수 있는 권한이 없습니다. |
하위 애플리케이션이 성공적으로 생성되면 다음과 같은 응답을 받게 됩니다.
{
"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"
]
} name , description 및 redirectUris 는 요청에서 수신된 내용을 확인하는 것입니다. clientId 및 clientSecret 은 OIDC 프로세스를 수행할 때 하위 애플리케이션이 사용해야 하는 것입니다. 또한 나중에 애플리케이션을 관리하려면 clientId 가 필요합니다.
하위 애플리케이션의 비밀이 손상된 경우 다음을 통해 비밀을 재생성하도록 요청할 수 있습니다.
POST https://environment-url/services/client-id-of-child-application/regenerate-secret
Authorization: bearer {jwt-token}가능한 응답 코드는 다음과 같습니다:
| HTTP 상태 코드 | 이유 |
|---|---|
| 200 | 비밀번호가 다시 생성되었습니다. |
| 403 | 지정된 클라이언트 ID는 애플리케이션의 하위 항목이 아닙니다. |
| 404 | 지정된 클라이언트 ID를 사용하는 애플리케이션을 찾을 수 없습니다. |
보안 비밀이 성공적으로 재생성되면 다음과 같은 응답을 받게 됩니다.
{
"clientSecret": "regenerated-client-secret"
}하위 애플리케이션은 하위 애플리케이션 소유자가 우리가 제공하는 발행된 토큰의 수명 주기를 관리할 수 있도록 단기 액세스 토큰 및 장기 새로 고침 토큰으로 교환할 수 있는 인증 코드(부여)와 최종적으로 생성되는 명시적 동의 흐름을 따릅니다. 통제된 하위 애플리케이션에 대한 승인 및 토큰 문제를 나열하는 편리한 API입니다.
그런 다음 표준 공개 ID 연결 끝점(introection 및 revocaton)을 사용하여 이러한 토큰을 검사하고 취소할 수 있습니다.
특정 하위 서비스에 대한 보조금 목록을 얻으려면 다음을 수행하십시오.
GET https://environment-url/services/{service-id}/grants특정 하위 서비스 부여에 대해 발급된 토큰 목록을 얻으려면 다음을 수행하세요.
GET https://environment-url/services/{service-id}/grants/{grant-id}/tokens이 API를 사용하여 조직의 서비스에 대한 사용자 액세스 권한을 얻을 수 있습니다. 요청은 다음과 같습니다
GET https://environment-url/services/{service-id}/organisations/{organisation-id}/users/{user-id}
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 서비스 ID | URL | 와이 | 서비스의 DfE 로그인 식별자 |
| 조직 ID | URL | 와이 | 조직의 DfE 로그인 식별자 |
| 사용자 ID | URL | 와이 | 사용자의 DfE 로그인 식별자 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
그러면 다음 형식으로 응답이 반환됩니다.
{
"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"
}
]
}참고: 사용자가 지정된 서비스를 갖고 있지 않거나 명시된 조직에 속하지 않는 경우 상태 코드 404(찾을 수 없음) 이 반환됩니다.
이 API를 사용하여 사용자와 연결된 조직을 가져올 수 있습니다. 요청은 다음과 같습니다.
GET https://environment-url/users/{user-id}/organisations
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 사용자 ID | URL | 와이 | 사용자의 DfE 로그인 식별자 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
그러면 다음 형식으로 응답이 반환됩니다.
[
{
"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
},
]이 API 엔드포인트를 사용하여 서비스 또는 하위 서비스 중 하나와 연결된 역할을 가져올 수 있습니다. 요청은 다음과 같습니다.
GET https://environment-url/services/{client-id}/roles
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 클라이언트 ID | URL | 와이 | 서비스의 DfE 로그인 클라이언트 식별자 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
가능한 응답 코드는 다음과 같습니다.
| HTTP 상태 코드 | 이유 |
|---|---|
| 200 | 요청된 클라이언트 ID에 대한 역할 목록(비어 있을 수 있음)이 성공적으로 검색되었습니다. |
| 403 | 지정된 클라이언트 ID는 귀하의 서비스 또는 서비스의 하위 서비스가 아닙니다. |
| 404 | 지정된 클라이언트 ID로 서비스를 찾을 수 없습니다. |
그러면 다음 형식으로 응답이 반환됩니다.
[
{
"name": "Role 1 Name",
"code": "Role1Code",
"status": "Active"
},
{
"name": "Role 2 Name",
"code": "Role2Code",
"status": "Inactive"
}
]또는 역할을 찾을 수 없는 경우 다음을 수행합니다.
[]
이 API를 사용하여 사용자와 연결된 조직을 가져올 수 있습니다. 요청은 다음과 같습니다.
GET https://environment-url/users/{user-id}/v2/organisations
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 사용자 ID | URL | 와이 | 사용자의 DfE 로그인 식별자 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
그러면 다음 형식으로 응답이 반환됩니다.
[
{
"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"
},
] 인증 토큰(iss 속성)에 정의된 대로 필터 없이 사용자 목록을 얻을 수 있습니다.
요청은 다음과 같습니다.
GET https://environment-url/users?page=1&pageSize=25
Authorization: bearer {jwt-token}page 및 pageSize 변수는 선택 사항이며 기본값은 각각 1과 25입니다. 이러한 변수를 사용하면 호출자가 결과 페이지를 반복할 수 있습니다(응답 본문의 속성을 사용하여 레코드 및 페이지 수 계산).
응답 본문에는 다음 속성이 포함되어 있습니다(아래 응답 예시).
| 이름 | 설명 |
|---|---|
| 사용자 | 사용자 세부정보 배열(하위 조직 개체 포함) |
| 레코드 수 | 보고된 총 기록 수 |
| 페이지 | 현재 페이지 번호 |
| 페이지 수 | 총 페이지 수 |
응답 예시
{ "사용자": [
{ "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "조직": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "이름": "교육부", "범주": "002", "유형": null, "URN": null, "UID": null, "UKPRN ": null, "설립 번호": "001", "상태": 1, "ClosedOn": null, "주소": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "전화": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "중앙 정부 부서", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "" , "ProviderTypeName": "정부 기관", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019-02-20T14:27:59.020Z", "updatedAt": "2019-02-20T14:28:38.223Z"
}, "roleName": "승인자", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "존슨", "givenName": "로저"
}
], "numberOfRecords": 1, "페이지": 1, "numberOfPages": 1} 인증 토큰(iss 속성)에 정의된 필터를 사용하여 사용자 목록을 얻을 수 있습니다.
요청은 다음과 같습니다.
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}page 및 pageSize 변수는 선택 사항이며 기본값은 각각 1과 25입니다. 이러한 변수를 사용하면 호출자가 결과 페이지를 반복할 수 있습니다(응답 본문의 속성을 사용하여 레코드 및 페이지 수 계산). 상태(from 및 to)는 선택 사항이며 현재 0을 허용합니다. 날짜 범위는 7일만 허용됩니다. 날짜는 예에 표시된 대로 URL 인코딩 형식이어야 합니다.
기간 확인 기간이 7일을 초과하면 오류 메시지를 보냅니다. 필터의 시작 날짜만 시작 날짜로부터 7일 후에 사용자를 업데이트합니다. 필터의 현재 날짜만 해당 날짜로부터 7일 전에 사용자가 업데이트됩니다. 날짜를 지정하지 않으면 지금부터 7일 전까지 사용자가 업데이트됩니다.
응답 본문에는 다음 속성이 포함되어 있습니다(아래 응답 예시).
| 이름 | 설명 |
|---|---|
| 사용자 | 사용자 세부정보 배열(하위 조직 개체 포함) |
| 레코드 수 | 보고된 총 기록 수 |
| 페이지 | 현재 페이지 번호 |
| 페이지 수 | 총 페이지 수 |
| 경고(선택사항) | 7일간의 사용자만 가져올 때만 표시됩니다. |
응답 예시
{ "사용자": [
{ "approvedAt": "2019-06-19T15:09:58.683Z", "updatedAt": "2019-06-19T15:09:58.683Z", "조직": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "이름": "교육부", "범주": "002", "유형": null, "URN": null, "UID": null, "UKPRN ": null, "설립 번호": "001", "상태": 1, "ClosedOn": null, "주소": null, "phaseOfEducation": null, "statutoryLowAge": null, "statutoryHighAge": null, "전화": null, "regionCode": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID": "", "UPIN": "", "PIMSProviderType": "중앙 정부 부서", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "" , "ProviderTypeName": "정부 기관", "GIASProviderType": "", "PIMSProviderTypeCode": "", "createdAt": "2019-02-20T14:27:59.020Z", "updatedAt": "2019-02-20T14:28:38.223Z"
}, "roleName": "승인자", "roleId": 10000, "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "존슨", "givenName": "로저"
}
], "numberOfRecords": 1, "page": 1, "numberOfPages": 1, "warning": "7일간의 데이터만 가져올 수 있습니다."}카테고리 ID를 해석하려면 여기를 참조하세요.
서비스에 권한이 있는 경우 서비스 범위(역할 정책 조건에 따라) 내에 있는 조직에 대한 승인자 목록을 얻을 수 있습니다.
요청은 다음과 같습니다.
GET https://environment-url/users/approvers?page=1&pageSize=25
Authorization: bearer {jwt-token}page 및 pageSize 변수는 선택 사항이며 기본값은 각각 1과 25입니다. 이러한 변수를 사용하면 호출자가 결과 페이지를 반복할 수 있습니다(응답 본문의 속성을 사용하여 레코드 및 페이지 수 계산).
응답 본문에는 다음 속성이 포함되어 있습니다(아래 응답 예시).
| 이름 | 설명 |
|---|---|
| 사용자 | 사용자 세부정보 배열(하위 조직 개체 포함) |
| 레코드 수 | 보고된 총 기록 수 |
| 페이지 | 현재 페이지 번호 |
| 페이지 수 | 총 페이지 수 |
응답 예시
가능한 응답 코드는 다음과 같습니다:
| HTTP 상태 코드 | 이유 |
|---|---|
| 200 | 귀하의 요청이 승인되었습니다 |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 403 | 귀하의 애플리케이션에는 조직의 승인자를 얻을 수 있는 권한이 없습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
{ "사용자": [
{ "조직": { "id": "13F20E54-79EA-4146-8E39-18197576F023", "name": "교육부", "category": { "id": "002", "name": " 지자체"
}, "urn": null, "uid": null, "ukprn": null, "설립 번호": "001", "status": { "id": 1, "name": "열기"
}, "closedOn": null, "address": null, "telephone": null, "statutoryLowAge": null, "statutoryHighAge": null, "legacyId": "1031237", "companyRegistrationNumber": "1234567", "ProviderProfileID ": "", "UPIN": "", "PIMSProviderType": "중앙 정부 부서", "PIMSStatus": "", "DistrictAdministrativeName": "", "OpenedOn": "2007-09-01T00:00:00.0000000Z", "SourceSystem": "", "ProviderTypeName": "정부 기관", "GIASProviderType": "", "PIMSProviderTypeCode": ""
}, "roleId": 10000, "roleName": "승인자", "userId": "21D62132-6570-4E63-9DCB-137CC35E7543", "userStatus": 1, "email": "[email protected]", "familyName": "존슨", "givenName": "로저"
}
], "numberOfRecords": 1, "페이지": 1, "numberOfPages": 1}이 API를 사용하여 역할별로 필터링하는 조직 사용자를 얻을 수 있습니다. 요청은 다음과 같습니다.
GET https://environment-url/organisations/{UKPRN}/users?roles=role1,role2
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| UKPRN | URL | 와이 | 조직의 UKPRN |
| 역할 | URL | N | 조직 사용자 목록을 필터링하는 사용자 역할 코드 |
| jwt 토큰 | 헤더 | 와이 | 인증을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
가능한 응답 코드는 다음과 같습니다.
| HTTP 상태 코드 | 이유 |
|---|---|
| 200 | 요청한 조직에 대한 역할이 성공적으로 검색되었습니다. |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 403 | 애플리케이션에 이 조직의 사용자를 검색할 권한이 없습니다. |
| 404 | 요청한 조직에 대해 지정된 역할을 가진 사용자를 찾을 수 없어 배열이 비어 있습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
그러면 다음 형식으로 응답이 반환됩니다.
{
"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"
]
}
]
}필터링된 기준으로 조직 사용자 검색
위 API를 사용하여 이메일 주소나 userId와 같은 필터링된 기준을 기반으로 조직 사용자를 검색할 수도 있습니다. 요청은 다음과 같습니다
GET https://environment-url/organisations/{UKPRN}/[email protected]
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| UKPRN | URL | 와이 | 조직의 UKPRN |
| 이메일 | URL | N | 필터링을 위한 사용자의 이메일 주소 |
| jwt 토큰 | 헤더 | 와이 | 승인을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
응답 형식은 이전 API 호출과 동일하게 유지되므로 특정 기준으로 필터링할 수 있습니다.
이 API를 사용하여 역할별로 필터링하는 조직 사용자를 얻을 수 있습니다. 요청은 다음과 같습니다.
GET https://environment-url/organisations/{UPIN}/users?roles=role1,role2
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 업핀 | URL | 와이 | 조직을 위한 UPIN |
| 역할 | URL | N | 조직 사용자 목록을 필터링하는 사용자 역할 코드 |
| jwt 토큰 | 헤더 | 와이 | 승인을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
가능한 응답 코드는 다음과 같습니다.
| HTTP 상태 코드 | 이유 |
|---|---|
| 200 | 요청한 조직에 대한 역할이 성공적으로 검색되었습니다. |
| 400 | 귀하의 요청이 잘못되었습니다. 자세한 내용은 응답 본문에 제공됩니다. |
| 401 | JWT가 누락되었거나 유효하지 않습니다. |
| 403 | 애플리케이션에 이 조직의 사용자를 검색할 권한이 없습니다. |
| 404 | 요청한 조직에 대해 지정된 역할을 가진 사용자를 찾을 수 없어 배열이 비어 있습니다. |
| 500 | 서버에 오류가 발생했습니다. 비밀, API 키 또는 토큰과 같은 비밀이 올바르게 구성되었는지 확인하세요. 문제가 계속되면 지원팀에 문의하여 도움을 받으세요. |
그러면 다음 형식으로 응답이 반환됩니다.
{
"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"
]
}
]
}필터링된 기준으로 조직 사용자 검색
위 API를 사용하여 이메일 주소나 userId와 같은 필터링된 기준을 기반으로 조직 사용자를 검색할 수도 있습니다. 요청은 다음과 같습니다
GET https://environment-url/organisations/{UPIN}/[email protected]
Authorization: bearer {jwt-token}가변 데이터 항목은 다음과 같습니다.
| 이름 | 위치 | 필수의 | 설명 |
|---|---|---|---|
| 업핀 | URL | 와이 | 조직을 위한 UPIN |
| 이메일 | URL | N | 필터링을 위한 사용자의 이메일 주소 |
| jwt 토큰 | 헤더 | 와이 | 승인을 위한 JWT 토큰은 귀하에게 제공되는 API 비밀을 사용하여 서명되어야 합니다. |
응답 형식은 이전 API 호출과 동일하게 유지되므로 특정 기준으로 필터링할 수 있습니다.
| ID | 설명 |
|---|---|
| 001 | 시설(아래 시설 유형 참조) |
| 002 | 지방자치단체 |
| 003 | 기타 기존 조직 |
| 004 | 초기 설정 |
| 008 | 기타 이해관계자 |
| 009 | 교육 제공자 |
| 010 | 다중 아카데미 신뢰 |
| 011 | 정부 |
| 012 | 기타 GIAS 이해관계자 |
| 013 | 단일 아카데미 신탁 |
| 050 | 소프트웨어 공급업체 |
| 051 | 추가 교육 |
