{"openapi":"3.0.3","info":{"title":"IM1 PFS Auth API","description":"## Overview\n\nIM1 PFS Auth provides a means of authenticating a user and establishing an IM1 session to access Patient-Facing Services (PFS).\nThe API authenticates a user via an NHS login token and routes requests to the specified supplier system and ODS code.\nIf the user's account is successfully matched, the API returns the new IM1 session details.\n\n![IM1 PFS Auth API High-level Diagram](https://raw.githubusercontent.com/NHSDigital/im1-pfs-auth/main/specification/assets/overview.drawio.svg)\n\nYou can use this API to:\n\n- authenticate a user and initiate a session with the appropriate supplier system for:\n  - a specific patient\n  - all patients that the logged-in user has an online account for\n\n## Who can use this API\nYou can only use this API if you have a valid legal basis.\nBefore investing significant time in development, confirm that your use case is appropriate by [contacting us](https://digital.nhs.uk/developer/help-and-support).\n\nYou must do this before you can go live.\n\n## API status and roadmap\nThis API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\n\n## Network access\nThis API is available on the internet.\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\n\nThis API supports [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) access type with the following access modes:\n\n| Access mode                   | Access type            |\n|-------------------------------|------------------------|\n| Patient access                | User-restricted        |\n\nFor more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation).\n\n### User-restricted access\n\nThis API has user-restricted access, meaning an end user must be present, authenticated and authorised.\n\n#### Patient access mode\nIf the end user is a patient then you must use this access mode.\n\n[Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode)\n\n\n## Headers\nThis API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. For example, NHSE-Request-Id, nhse-request-id are treated the same.\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nEach endpoint lists its own specific errors in the Responses section. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\n## Open source\nYou might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:\n\n| Resource         | Description                                               | Links                                                     |\n| ---------------- | --------------------------------------------------------- | --------------------------------------------------------- |\n| IM1 PFS Auth API | Source code for the API proxy, sandbox and specification. | [GitHub repo](https://github.com/NHSDigital/im1-pfs-auth) |\n\n## Environments and testing\n| Environment       | Base URL                                           |\n| ----------------- | -------------------------------------------------- |\n| Sandbox           | `https://sandbox.api.service.nhs.uk/im1-pfs-auth/` |\n| Integration test  | `https://int.api.service.nhs.uk/im1-pfs-auth/`     |\n\n### Sandbox testing\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing)\n\n* is for early developer testing\n* only covers a limited set of scenarios\n* is open access, so does not allow you to test authorisation\n\n[![Import Postman Collection](https://img.shields.io/badge/Import-Postman%20Collection-orange?logo=postman)](https://raw.githubusercontent.com/NHSDigital/im1-pfs-auth/main/postman/postman_collection.json)\n\nImport the  postman collection to run requests against sandbox.\n\n## Contact us\nFor help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).\n","version":"0.1"},"servers":[{"url":"https://sandbox.api.service.nhs.uk/im1-pfs-auth/"},{"url":"https://int.api.service.nhs.uk/im1-pfs-auth/"},{"url":"https://internal-dev.api.service.nhs.uk/im1-pfs-auth"}],"paths":{"/authenticate":{"post":{"tags":["sessions"],"summary":"Create a session","description":"## Overview\n\nA user can authenticate and establish a session with GPIT supplier systems.\n\nThis endpoint:\n  - Verifies the user access token\n  - Determines which supplier system to forward requests onto\n  - Transforms response\n\n## Access modes\n\nThis endpoint supports the following access modes:\n- Patient access\n\n## Sandbox test scenarios\n\nSee the postman collection for example requests.\n\n| Scenario               | Request                                                                                     | Response                                                    |\n| ---------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |\n| Successful request     | Valid request with forward to value of https://example.com and ods code value of A29929     | HTTP Status 201 Success response                            |\n\n### Sandbox constraints\n  - Headers that are not required for the scenario are not validated and are disregarded.\n\nOr perhaps you'd like to try out the sandbox using our 'Try it out' feature.\n","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"name":"NHSE-Application-ID","in":"header","description":"The identifier of the calling application e.g. EMIS:  X-API-ApplicationId, and TPP: providerId.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"NHSE-Request-ID","in":"header","description":"An ID which you can use to track transactions across multiple systems. Must be a universally unique identifier (UUID) (ideally version 4). Mirrored back in a response header.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string","format":"uuid","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"name":"NHSE-Forward-To","in":"header","description":"The GPIT Supplier base URL to forward requests to.\n\nTPP:\n| Environment | Allowed URLs                    |\n|-------------|---------------------------------|\n| Integration | https://systmonline2.tpp-uk.com |\n| Production  | https://systmonline.tpp-uk.com  |\n\nEMIS:\n| Environment | Allowed URLs                        |\n|-------------|-------------------------------------|\n| Integration | https://nhs70apptest.emishealth.com |\n| Production  | https://api.pfs.emis-x.uk           |\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}},{"name":"NHSE-ODS-Code","in":"header","description":"The ODS code of the GP practice to start a session with.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"A29929"}},{"name":"NHSE-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. Must be a universally unique identifier (UUID) (ideally version 4). Mirrored back in a response header.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string","format":"uuid","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}],"responses":{"201":{"description":"The session was created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseModel"}}}},"4XX":{"description":"Errors will be returned for the first error encountered in the request. An error occurred as follows:\n\n| HTTP status | Error code              | Description                                                                                                                               |\n| ----------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| 400         | `BAD_REQUEST`           | Missing header.                                                                                                                           |\n| 400         | `BAD_REQUEST`           | Invalid header.                                                                                                                           |\n| 401         | `UNAUTHORIZED`          | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |\n| 404         | `NOT_FOUND`             | Resource not found.                                                                                                                       |\n| 403         | `FORBIDDEN`             | Access denied to resource.                                                                                                                |\n| 408         | `REQUEST_TIMEOUT`       | Request timed out.                                                                                                                        |\n| 429         | `TOO_MANY_REQUESTS`     | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"missingValueError":{"externalValue":"./examples/errors.yaml#/MissingValueError"},"invalidValueError":{"externalValue":"./examples/errors.yaml#/InvalidValueError"},"notFoundError":{"externalValue":"./examples/errors.yaml#/NotFoundError"},"accessDeniedError":{"externalValue":"./examples/errors.yaml#/AccessDeniedErrorError"},"forbiddenError":{"externalValue":"./examples/errors.yaml#/ForbiddenError"},"timeoutError":{"externalValue":"./examples/errors.yaml#/TimeoutError"},"throttledError":{"externalValue":"./examples/errors.yaml#/ThrottledError"}}}}},"5XX":{"description":"Errors will be returned for the first error encountered in the request. An error occurred as follows:\n\n| HTTP status | Error code              | Description                                       |\n| ----------- | ----------------------- | ------------------------------------------------- |\n| 500         | `SERVER_ERROR`          | An unexpected internal server error has occurred. |\n| 502         | `BAD_GATEWAY`           | An error downstream has occurred.                 |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"serverError":{"externalValue":"./examples/errors.yaml#/InternalServerError"},"downstreamError":{"externalValue":"./examples/errors.yaml#/DownstreamError"}}}}}},"deprecated":false,"security":[{"nhs-login-p9":[]}]}}},"components":{"schemas":{"ResponseModel":{"oneOf":[{"$ref":"#/components/schemas/EMISResponseModel"},{"$ref":"#/components/schemas/TPPResponseModel"}]},"EMISResponseModel":{"required":["sessionId","endUserSessionId","supplier","odsCode","user","patients"],"type":"object","properties":{"sessionId":{"minLength":1,"type":"string"},"endUserSessionId":{"type":"string"},"supplier":{"enum":["EMIS"],"type":"string"},"odsCode":{"type":"string"},"user":{"$ref":"#/components/schemas/EMISPersonModel"},"patients":{"type":"array","items":{"$ref":"#/components/schemas/EMISPersonModel"}}},"additionalProperties":false},"TPPResponseModel":{"required":["sessionId","supplier","odsCode","onlineUserId","user","patients"],"type":"object","properties":{"sessionId":{"minLength":1,"type":"string"},"supplier":{"enum":["TPP"],"type":"string"},"odsCode":{"type":"string"},"onlineUserId":{"type":"string"},"user":{"$ref":"#/components/schemas/TPPPersonModel"},"patients":{"type":"array","items":{"$ref":"#/components/schemas/TPPPersonModel"}}},"additionalProperties":false},"DemographicsModel":{"required":["firstName","surname","title","dateOfBirth"],"type":"object","properties":{"firstName":{"type":"string"},"surname":{"type":"string"},"title":{"type":"string"},"dateOfBirth":{"type":"string"}}},"PatientIdentifierModel":{"required":["value","type"],"type":"object","properties":{"value":{"type":"string"},"type":{"type":"string"}}},"EMISPersonModel":{"allOf":[{"$ref":"#/components/schemas/DemographicsModel"},{"required":["userPatientLinkToken","patientIdentifiers","permissions"],"type":"object","properties":{"userPatientLinkToken":{"type":"string"},"patientIdentifiers":{"type":"array","items":{"$ref":"#/components/schemas/PatientIdentifierModel"}},"permissions":{"$ref":"#/components/schemas/EMISPermissionsModel"}}}]},"EMISPermissionsModel":{"required":["appointmentsEnabled","demographicsUpdateEnabled","epsEnabled","medicalRecordEnabled","onlineTriageEnabled","practicePatientCommunicationEnabled","prescribingEnabled","recordSharingEnabled","recordViewAuditEnabled","medicalRecord"],"type":"object","properties":{"appointmentsEnabled":{"type":"boolean"},"demographicsUpdateEnabled":{"type":"boolean"},"epsEnabled":{"type":"boolean"},"medicalRecordEnabled":{"type":"boolean"},"onlineTriageEnabled":{"type":"boolean"},"practicePatientCommunicationEnabled":{"type":"boolean"},"prescribingEnabled":{"type":"boolean"},"recordSharingEnabled":{"type":"boolean"},"recordViewAuditEnabled":{"type":"boolean"},"medicalRecord":{"$ref":"#/components/schemas/EMISMedicalRecordModel"}}},"EMISMedicalRecordModel":{"required":["recordAccessScheme","allergiesEnabled","consultationsEnabled","immunisationsEnabled","documentsEnabled","medicationEnabled","problemsEnabled","testResultsEnabled"],"type":"object","properties":{"recordAccessScheme":{"enum":["Legacy","None","CoreSummaryCareRecord","DetailedCodedCareRecord"],"type":"string"},"allergiesEnabled":{"type":"boolean"},"consultationsEnabled":{"type":"boolean"},"immunisationsEnabled":{"type":"boolean"},"documentsEnabled":{"type":"boolean"},"medicationEnabled":{"type":"boolean"},"problemsEnabled":{"type":"boolean"},"testResultsEnabled":{"type":"boolean"}}},"TPPPersonModel":{"allOf":[{"$ref":"#/components/schemas/DemographicsModel"},{"required":["patientId","patientIdentifiers","permissions"],"type":"object","properties":{"patientId":{"type":"string","nullable":true},"patientIdentifiers":{"type":"array","items":{"$ref":"#/components/schemas/PatientIdentifierModel"}},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/TPPPermissionsModel"}}}}]},"TPPPermissionsModel":{"required":["description","serviceIdentifier","status","statusDescription"],"type":"object","properties":{"description":{"enum":["Full Clinical Record","Appointments","Request Medication","Questionnaires","Summary Record","Detailed Coded Record","Messaging","View Sharing Status","Record Audit","Change Pharmacy","Manage Sharing Rules And Requests","Access SystmConnect"],"type":"string"},"serviceIdentifier":{"type":"integer"},"status":{"enum":["A","U","N","G","O"],"type":"string"},"statusDescription":{"enum":["Available","Unavailable","Not offered by unit","Only available to GMS registered patients","Other"],"type":"string"}}},"OperationOutcome":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"minItems":1,"type":"array","items":{"required":["severity","code"],"type":"object","properties":{"severity":{"enum":["fatal","error","warning","information"],"type":"string","description":"Severity of the error."},"code":{"enum":["forbidden","processing","exception"],"type":"string","description":"FHIR error code."},"details":{"type":"object","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"enum":["https://fhir.nhs.uk/R4/CodeSystem/IM1-PFS-Auth-ErrorOrWarningCode"],"type":"string","description":"URI of the coding system specification."},"version":{"type":"string","description":"Version of the coding system in use."},"code":{"type":"string","description":"Symbol in syntax defined by the system."},"display":{"type":"string","description":"Representation defined by the system."}}}}},"description":"Internal error code."},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change."},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error."}}},"description":"List of issues that have occurred."}},"description":"Outcome of an operation as a result of an error.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n"}},"securitySchemes":{"nhs-login-p9":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/nhs-login-p9"}}}}