Get a Software Statement Assertion for the given SoftwareStatementID.

GET /organisations/:OrganisationId/softwarestatements/:SoftwareStatementId/assertion

The response body is a signed JWT and the values found in the header and the payload of the SSA are specified below

Terminology

This specification uses the terms "access token", "authorization code", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "client secret", "grant type", "protected resource", "redirection URI", "refresh token", "resource owner", "resource server", "response type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and uses the term "Claim" defined by JSON Web Token (JWT) [RFC7519].

Organisation -- An organisation managing customer accounts (and operating banking APIs).
Primary Technical Contact -- The person at the org who creates an SSA and invokes a registration mechanism. This is an example of an [RFC7591] Client Developer.
Organisation ID -- The unique identifier for each directory participant.
Role -- An implementation of an authority; acts as an Identity Provider, certificate authority, and registry governing the participants in the UK API scheme.
Registration Endpoint -- OAuth 2.0 & [RFC7591] compliant endpoint
Software Statement Assertion (SSA) -- An implementation of an [RFC7591] software statement, signed by the Directory.
Trusted Third Party -- An organization working to initiate payments or consume account information.
Client Software -- software implementing an OAuth2 client, interacting with an org's registration endpoint.

Software Statement Assertion (SSA)

The SSA is a JSON Web Token (JWT) containing client metadata about an instance of client software. The JWT is issued and signed by the Directory.

SSA Payload

The payload of the SSA MUST be a compliant software statement according to [RFC7591]. The SSA MUST also be a compliant JWT according to [RFC7519]. The following metadata profiles the metadata in [RFC7591] and [RFC7519]:

Metadata	Description	Source Specification
`softwareid`	Unique Identifier for Client Software	[RFC7591]
`iss`	SSA Issuer	[RFC7519]
`iat`	Time SSA issued	[RFC7519]
`jti`	JWT ID	[RFC7519]
The following software metadata is additionally defined for this profile:
Metadata	Description	Field Size
---------	------------	-----------
`SoftwareClientId`	The Client ID Registered in Directory services used to access directory resources	Base62 GUID (22 chars)
`SoftwareClientDescription`	Human-readable detailed description of the client	Max256Text
`SoftwareClientName`	Human-readable Software statement Name	Max40Text
`SoftwareClientUri`	The website or resource root uri	Max256Text
`SoftwareVersion`	The version number of the software should an org choose to register and / or maintain it	decimal
`SoftwareEnvironment`	Requested additional field to avoid certificate check	Max256Text
`softwareJwksUri`	Contains all active signing and network certs for the software	Max256Text
`SoftwareJwksRevokedUri`	Contains all revoked signing and network certs for the software	Max256Text
`SoftwareLogoUri`	Link to the Org logo.	Max256Text
`SoftwareMode`	Org Requested additional field to indicate that this software is `Test` or `Live` the default is `Live`. Impact and support for `Test` software is up to the Org.	Max40Text
`SoftwareOnBehalfOf`	A reference to fourth party organisation resource on the Directory if the registering app is acting on behalf of another.	Max40Text
`SoftwarePolicyUri`	A link to the software's policy page	Max256Text
`SoftwareRedirectUris`	Registered client callback endpoints as registered with RTS	A string array of Max256Text items
`SoftwareAuthorityClaims`	A multi value list of roles that this software is authorized to perform.	A string array of authority claims items
`SoftwareTosUri`	A link to the software's terms of service page	Max256Text
The following Organisational metadata is defined for this profile:
Metadata	Description	Field Size
---------	------------	-----------
`OrganisationAuthorityClaims`	Claims object for the organisation detailing all the authorisation roles
`OrgStatus`	Included to cater for voluntary withdrawal from directory scenarios	`Active`, `Revoked`, or `Withdrawn`
`OrgId`	The Unique Organisation Id.	Max35Text
`OrgName`	Legal Entity Identifier or other known organisation name	Max140Text
`OrgContacts`	JSON array of objects containing a triplet of name, email, and phone number	Each item Max256Text
`OrgJwksUri`	Contains all active signing and network certs for the organisation	Max256Text
`OrgJwksRevokedUri`	Contains all revoked signing and network certs for the organisation	Max256Text

SSA header

The SSA header MUST comply with [RFC7519].

Metadata	Description	Comments
`typ`	MUST be set to `JWT`
`alg`	MUST be set to `ES256` or `PS256` note the majority of ecosystems use RSA keys so support for PS256 is critical
`kid`	The kid will be kept the same as the `x5t` parameter. (X.509 Certificate SHA-1 Thumbprint) of the signing certificate.

Example SSA

The elements defined in the software statement will consist of the following values. Note that there are inconsistent applications of booleans or "Active" strings in the current data model. Note that there are inconsistent applications of status flags case sensitivity. The attributes required to be displayed by Orgs.

{
  "typ": "JWT",
  "alg": "ES256",
  "kid": "ABCD1234"
}
{
  "iss": "Example Ltd",
  "iat": 1492756331,
  "jti": "id12345685439487678",
  "SoftwareEnvironment": "production",
  "SoftwareMode": "live",
  "SoftwareId": "65d1f27c-4aea-4549-9c21-60e495a7a86f",
  "SoftwareClientId": "xClient Unique ID",
  "SoftwareClientName": "Amazon Prime Movies",
  "SoftwareClientDescription": "Amazon Prime Movies is a moving streaming service",
  "SoftwareVersion": "2.2",
  "SoftwareClientUri": "https://prime.amazon.com",
  "SoftwareRedirectUris": [
    "https://prime.amazon.com/cb",
    "https://prime.amazon.co.uk/cb"
  ],
  "SoftwareAuthorityClaims": {
    "AuthorisationDomains": [
      {
        "AuthorisationDomain": "PDS2",
        "Roles": [
          {
            "Role": "ASPSP",
            "Status": "Active"
          }
        ]
      },
      {
        "AuthorisationDomain": "Pensions",
        "Roles": [
          {
            "Role": "TPP",
            "Status": "Active"
          },
          {
            "Role": "ASPSP",
            "Status": "Active"
          }
        ]
      }
    ]
  },
  "OrganisationAuthorityClaims": [
    {
      "AuthorityId": "123",
      "RegistrationId": "111111",
      "AuthorisationDomains": [
        {
          "AuthorisationDomain": "PDS2",
          "Roles": [
            {
              "Role": "ASPSP",
              "Authorisations": [
                {
                  "Status": "Active",
                  "MemberState": "GB"
                },
                {
                  "Status": "Active",
                  "MemberState": "IL"
                }
              ]
            },
            {
              "Role": "AISP",
              "Authorisations": [
                {
                  "Status": "Active",
                  "MemberState": "GB"
                },
                {
                  "Status": "Active",
                  "MemberState": "IL"
                }
              ]
            }
          ]
        },
        {
          "AuthorisationDomain": "Pensions",
          "Roles": [
            {
              "Role": "ASPSP",
              "Authorisations": [
                {
                  "Status": "Active",
                  "MemberState": "GB"
                },
                {
                  "Status": "Active",
                  "MemberState": "IL"
                }
              ]
            },
            {
              "Role": "TPP",
              "Authorisations": [
                {
                  "Status": "Active",
                  "MemberState": "GB"
                },
                {
                  "Status": "Active",
                  "MemberState": "IL"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "SoftwareLogoUri": "https://mycompanyprofile.com/logo.png",
  "OrgStatus": "Active",
  "OrgId": "My Company's ID",
  "OrgName": "Registered Name",
  "OrgContacts": [
    {
      "name": "contact name",
      "email": "contact@contact.com",
      "phone": "+447890130558",
      "type": "business"
    },
    {
      "name": "contact name",
      "email": "contact@contact.com",
      "phone": "+447890130558",
      "type": "technical"
    }
  ],
  "OrgJwksUri": "https://jwks.raidiam.ts.uk/org_id/org_id.jkws",
  "OrgJwksRevokedUri": "https://jwks.raidiam.ts.uk/org_id/revoked/org_id.jkws",
  "SoftwareJwksUri": "https://jwks.raidiam.ts.uk/org_id/software_id.jkws",
  "SoftwareJwksRevokedUri": "https://jwks.raidiam.ts.uk/org_id/revoked/software_id.jkws",
  "SoftwarePolicyUri": "https://myapp.com/policy.html",
  "SoftwareTosUri": "https://myapp.com/tos.html",
  "SoftwareOnBehalfOf": "A Mediator Ltd"
}
{
  Signature
}

Automated Client Registration

An organisation MAY use automated client registration to submit an SSA in exchange for client credentials for use as a client against an OAuth 2.0 Authorization Server. It is RECOMMENDED for Orgs to support the automated client registration mechanism. A large number of claims that OpenID Connect OPs could support as part of the RFC7591 request are detailed https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata and should be followed if not explicitly referenced in the Software Statement Assertion claim set.

Request Validation

Prior to issuing a client registration response, the Orgs MUST perform the following checks

The Org SHOULD check whether the initiated TLS connection is the same Org as listed in the SSA.
In the case where a gateway or other piece of infrastructure pre-terminates the MATLS channel in front of the registration endpoint, the certificate used to initiate the connection or some part of that certificate (such as DN & Issuer) SHOULD be made available to the Org for validation against the claims in the SSA.
The registration request MUST be signed with a key contained in the JWKS referenced in the SSA included with the request. This ensures that a holder-of-key proof-of-possession is performed proving that the app was the originally intended recipient of the SSA when the directory services issued it.
The SSA MUST be validated according to [RFC7519], including validation of the signature and validity window. JWT signature must be validated, this involves retrieving the jwks keyset for both the directory and the app. The keystore location will be published as part of the directory specification, The App's will be included in the software statement.

SSA Lifetime

The SSA's Lifetime / Validity period is not defined by RTS. Orgs in the directory ecosystem are required to implement pragmatic time ranges in which to accept an SSA. For example, an Org that has implemented Dynamic Client Registration may choose to accept SSA's that were issued no earlier than 1 minute prior to their presentation however Orgs that only support manual registration may need to accept SSAs that were issued 30 minutes prior as the elapsed time period between generation and use between these two flows is expected to differ significantly.

Request

Path Parameters

OrganisationId OrganisationIdrequired

Possible values: non-empty and <= 40 characters, Value must match regular expression ^[^<>]*$

The organisation ID

SoftwareStatementId SoftwareStatementIdrequired

Possible values: <= 40 characters, Value must match regular expression ^[^<>]*$

The software statement ID

Header Parameters

x-fapi-auth-date string

Possible values: Value must match regular expression ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$

The time when the PSU last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC

x-fapi-customer-ip-address string

The PSU's IP address if the PSU is currently logged in with the TPP.

x-fapi-interaction-id string

An RFC4122 UID used as a correlation id.

x-customer-user-agent string

Indicates the user-agent that the PSU is using.

Responses

Response Headers

x-fapi-interaction-id
string

application/jwt
application/json

Schema

Schema

string

Possible values: <= 4000 characters, Value must match regular expression ^[^<>]*$

Schema

Schema

string

Possible values: <= 4000 characters, Value must match regular expression ^[^<>]*$

Bad Request

Response Headers

x-fapi-interaction-id
string

application/json

Schema
Example (from schema)

Schema

errors string[]

Validation Error messages

{
  "errors": [
    "string"
  ]
}

Get a Software Statement Assertion for the given SoftwareStatementID.

/organisations/:OrganisationId/softwarestatements/:SoftwareStatementId/assertion

Software Statement Assertion (SSA)

SSA Payload​

SSA header​

Example SSA​

Automated Client Registration

Request Validation​

SSA Lifetime​

Request​

Path Parameters

Header Parameters

Responses​

SSA Payload

SSA header

Example SSA

Request Validation

SSA Lifetime

Request

Responses