> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Starling Bank

## Links

* [Developer Portal](https://developer.starlingbank.com/)

## Custom API

starling, starling-sandbox

## Scopes

* Account Information 🔒
* Payment Initiation 🔒

### Live and Sandbox Environment (AIS)

1. [Register a new account](https://developer.starlingbank.com/signup) on the platform
2. [Create an application](https://developer.starlingbank.com/application/new)
   1. Name your application
   2. Give your application a description, homepage url and redirect url
   3. Set the 'Redirect' to [https://auth.yapily.com/](https://auth.yapily.com/)
   4. Submit
3. Take a note of your **Client ID** and **Client Secret**
4. Add the *Client ID* as **Key** and *Client Secret* as **Secret** to your application in the [Yapily Console](https://console.yapily.com/)

**Note**: to upgrade your application to **Live** please refer to the **Going Live** section of the [Get Started](https://developer.starlingbank.com/get-started)

### Live Personal Accounts (AIS Only)

1. [Register for a new Starling developer account](https://developer.starlingbank.com/signup) on their website

2. [Create a Starling application](https://developer.starlingbank.com/application/new)

   1. Name your application
   2. Give your application a description, homepage url and redirect url
   3. Go to [Personal Access Token](https://developer.starlingbank.com/personal/list) tab and click on 'Connect Accounts'
   4. Follow the instructions on the screen in order to connect your account
   5. Go back to the [Personal Access](https://developer.starlingbank.com/personal/list) tab and click on 'Create Token' add a token name and select the following scopes: `account:read`, `balance:read`, `address:read`, `customer:read`, `transaction:read`
   6. Copy the token and make a POST request to the Yapily API endpoint [http://api.yapily.com/users/\{user-uuid}/consents](http://api.yapily.com/users/%7Buser-uuid%7D/consents) to add the token to create a consent resource for your application user

3. Use the Yapily consent token to sign requests for users' [financial data](/data/overview)

### Live and Sandbox Environment (PISP)

1. [Register for a new Starling developer account](https://developer.starlingbank.com/signup) on their website

2. [Create a Starling application](https://developer.starlingbank.com/application/new)

   1. Name your application
   2. Give your application a description, homepage url and redirect url
   3. Set the 'Redirect' to [https://auth.yapily.com/](https://auth.yapily.com/)
   4. Add Logo to your application.(It is required if permission upgrade for an application is to be requested.)
   5. Submit

3. Take a note of your **Client ID** and **Client Secret**.

4. Upload your KEYS:

   1. Create two pairs of public/private keys (Please refer \[Generate Key Pair Section below]). One pair is used to sign the API request and other pair is used as a rotation key which is used to sign new key uploads.
   2. Store the keys securely.
   3. Upload the public key part of the signing key pair to your application in the [Starling Developer Portal](https://developer.starlingbank.com/application/list) and generate **Key Uid**.
   4. Take a note of generated **Key Uid**.
   5. Click next to upload the public key part of the rotation key pair.
   6. The private key part of the signing key pair is to be uploaded in your application in the [Yapily Console](https://console.yapily.com/).
   7. The private key part of the rotation key pair is to be used to sign the new public key (the key used to sign the API). This is required only when an old signing key is to be replaced with new one.

5. Add the *Client ID* as **Key**, *Client Secret* as **Secret**, *Key Uid* as **Signing Key id** and private key part of signing key pair as **Private key** to your application in the [Yapily Console](https://console.yapily.com/). The private key should either be:

   1. A complete private key, across new lines and with headers and footers, such as -----BEGIN RSA PRIVATE KEY-----\` or
   2. A single line for the whole body of the signature without headers and footers.

**Note**:

* To upgrade your application to **Live** please refer to the **Going Live** section of the [Get Started](https://developer.starlingbank.com/get-started)
* PISPs need to apply for a scope upgrade to have Payment Initiation Service permissions. They can apply upgrade via the [Starling Developer Portal - Partners](https://developer.starlingbank.com/partner).
  1. Read the **Permission Upgrade Guide**
  2. Click the **Upgrade permissions** button.
  3. Select an application for which upgrade is required from the list. It will take you to the *Application Preview* page.
  4. Click next to go to the *Permissions* page.
  5. Select following permissions (or scopes) on the page: `account:read`, `balance:read`, `confirmation-of-funds:read`,address:read`, `payee:read`, `transaction:read`, `pay-local:read`, `mandate:read`, `standing-order:read`, `account-identifier:read`, `account-holder-name:read`, `account-holder-type:read`, `customer:read`, `customer:read`, `payee:create`, `pay-local:create`, `pay-local-once:create`, `pay-foreign:create`, `standing-order:create\`.
  6. Next, select the regulated status of your company.
  7. Download the **Partner Application Form**. Complete the form and upload it on the link provided on the same page.
  8. Click Next and provide your company details and submit the request.

### Generate Key Pair

The key requirements for Starling are as follows:

* Keys must be either RSA or ECDSA keys.
* RSA keys should have a length of either 2048 or 4096.
* ECDSA keys should have a length of 256.
* RSA keys should not be SSH keys. All valid RSA key bodies will start with MII.

The above requirement can be met as follows:

OpenSSL - Generate ECDSA or RSA pair using either of the following code snippets

#### RSA:

1. Create a 2048 bit key pair:

`openssl genrsa -out private_signing.key.pem 2048`
`openssl genrsa -out private_rotation.key.pem 2048`

2. Extract public key

`openssl rsa -in private_signing.key.pem -out public_signing.key -pubout`
`openssl rsa -in private_rotation.key.pem -out public_rotation.key -pubout`

#### ECDSA:

1. Create a key pair:

`openssl ecparam -genkey -name prime256v1 -noout -out private_signing.key.pem`
`openssl ecparam -genkey -name prime256v1 -noout -out private_rotation.key.pem`

2. Extract public key

`openssl ecparam -in private_signing.key.pem -out public_signing.key -pubout`
`openssl ecparam -in private_rotation.key.pem -out public_rotation.key -pubout`

Java - Generate ECDSA or RSA pair using either of the following code snippets

#### RSA:

`KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048, new SecureRandom());
KeyPair signingKey = keyPairGenerator.generateKeyPair();`

`String publicSigningKey = new String(Base64.getEncoder().encode(signingKey.getPublic().getEncoded()));
String privateSigningKey = new String(Base64.getEncoder().encode(signingKey.getPrivate().getEncoded()));`

`KeyPair rotationKey = keyPairGenerator.generateKeyPair();`

`String publicRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPublic().getEncoded()));
String privateRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPrivate().getEncoded()));`

#### ECDSA:

`KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC");
keyPairGenerator.initialize(256);
KeyPair signingKey = keyPairGenerator.generateKeyPair();`

`String publicKey = new String(Base64.getEncoder().encode(signingKey.getPublic().getEncoded()));
String privateKey = new String(Base64.getEncoder().encode(signingKey.getPrivate().getEncoded()));`

`KeyPair rotationKey = keyPairGenerator.generateKeyPair();`

`String publicRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPublic().getEncoded()));
String privateRotationKey = new String(Base64.getEncoder().encode(rotationKey.getPrivate().getEncoded()));`

## OpenBanking API

`starling_ob`, `starling_ob-sandbox`

### Links

* [Developer Portal](https://developer.starlingbank.com/docs/open-banking)

### Scopes

* Account Information 🔒

### Onboarding ASPSP's to Yapily Application

#### **OB Certificates**

**Precondition**: To connect to Starling OB institutions with OB certs a dynamic registration request (DCR) is needed.

**Pre-requisites for DCR:**

* Valid OBWAC / OBSEAL certificates
* SSA (downloaded from OBIE directory) - ***Optional***

#### Steps Required for DCR registration

1. **Download your SSA from the OBIE directory (optional - see step 3)**

   Open the OBIE Directory for your organisation, navigate to the SSA you want to use for the registration and generate the SSA. The downloaded SSA has to be passed as is to the registration endpoint; **do not alter the contents or format**.

2. Upload the signing (OBSEAL) and transport (OBWAC) certificates into V2 services

   **Request**

   ```shell theme={null}
   curl --location --request POST '[https://api.yapily.com/certificates/keys/](https://api.yapily.com/certificates/keys/)' \

   --header 'Authorization: Basic YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
   --header 'Content-Type: application/json' \
   --data-raw '[{
      "pem": "$YOUR_PUBLIC_KEY_AS_PEM",
      "key": "$YOUR_PRIVATE_KEY",
      "kid" : "$CERT_KID",
      "name" : "$CERTIFICATE_NAME"
   }]'
   ```

   **Response**

   ```json theme={null}
   {
   "id": "d16f87d3-4222-4173-b8b9-44aeccacae7d",
   ....
   }
   ```

   Save the id and remember for which kind of key it corresponds:
   e.g. `SIGNING_KEY_UUID = d16f87d3-4222-4173-b8b9-44aeccacae7d`

   Once you have done it for the signing key, do the same request for your transport key.

3. **Call the registration endpoint**

   The final step is to call the registration endpoint with the certificate UUIDs and the downloaded SSA:

   **Request**

   Do not alter the downloaded SSA. Pass directly to the register endpoint in its JWS format.

   ```shell theme={null}
   curl --location --request POST 'https://api.yapily.com/institutions/starling_ob/register' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
        --data-raw '{
               "signingKeyID": "$SIGNING_KEY_UUID",
               "transportKeyID": "$TRANSPORT_KEY_UUID",
               "ssa": "$DOWNLOADED_SSA"
        }'
   ```

   If you are not manually supplying the SSA, then you will need to add two additional request body parameters; `softwareStatementId` and `organisationId` - these must match the JWKS URL that corresponds to your OB certificates :

   ```shell theme={null}
   curl --location --request POST 'https://api.yapily.com/institutions/starling_ob/register' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer YOUR_APPLICATION_CREDENTIALS_AS_BASIC_AUTH' \
        --data-raw '{
               "signingKeyID": "$SIGNING_KEY_UUID",
               "transportKeyID": "$TRANSPORT_KEY_UUID",
               "softwareStatementId" : "N7i....",
               "organisationId" : "0014H...."
        }'
   ```

   **Response**

   ```json theme={null}
   {
      "id": "a0460a91-4b4c-422a-bbe6-bebe0b92e308"
   }
   ```

Note above ID, this will be the clientId which can be further used to Get, Modify, Delete registrations with Yapily

## Support

If you require technical support with certificate management, please contact [Support](/resources/support).