openapi: 3.0.0 info: title: Platform APIs version: 1.0.0 description: >- Platform APIs serve primarily for two purposes: * Authorisation service which generates access tokens required by Capitalise APIs (e.g. other Platform and Business API resources) * Managing resources exists in the platform (e.g. tenants, and soon to be live user management) contact: name: Capitalise email: engineering@capitalise.com url: https://capitalise.com paths: /tenants: post: summary: Create a tenant operationId: post-tenants requestBody: content: application/json: schema: $ref: '#/components/schemas/TenantsRequest' examples: {} description: A tenant is property or product within a company. tags: - Tenants responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/TenantsResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error security: - Platform access token: [] parameters: [] get: summary: Retrieve tenants operationId: get-tenants responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TenantsResponseGET' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error description: Retrieve all tenants security: - Platform access token: [] tags: - Tenants parameters: - schema: type: integer minimum: 0 in: query name: offset description: Count of tenants to offset - schema: type: integer maximum: 100 minimum: 0 in: query name: limit description: Count of tenants to return in the response allowEmptyValue: true /api-key: post: x-controller-name: APIKeyManager x-operation-name: createApiKey description: Generate an API Key summary: Generate an API Key tags: - Auth responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/APIKeyResponseDto' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Entity '500': description: Internal Server Error requestBody: content: application/json: example: name: My first API key partnerApiKey: API_PARTNER_KEY scopes: - profile:multiples - profile:read - profile:write - questionnaire:read - questionnaire:write - funding:read - funding:write - insights:read - scoring:read - offline_access expiresAt: '2021-11-24T18:03:28.241Z' schema: $ref: '#/components/schemas/APIKeyRequestDto' description: '' operationId: APIKeyManager.createApiKey /auth/login: post: x-controller-name: AuthorizationManager x-operation-name: login summary: Generate login token description: >- Login token is used to generate API key. Practically, this should be a one-off API call which allow you programmatically generate the access token to subsequently [generate API key](#tag/Auth/operation/APIKeyManager.createApiKey). tags: - Auth responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OAuth2AuthorizedTokenDto' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Entity '500': description: Internal Server Error requestBody: content: application/json: schema: $ref: '#/components/schemas/SignInRequestDto' operationId: AuthorizationManager.login security: [] /auth/token: post: summary: Generate platform access token operationId: post-auth-token responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/PlatformTokenResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error description: '' tags: - Auth security: - X-API-Key: [] parameters: - schema: type: string in: header name: X-API-Key description: API Key required: true - schema: type: string in: header name: Capitalise-tenant-id description: >- Optional field to restrict the access token access to the specified tenant. If not provided, the access token can manage all tenants. _Highly recommended for individual tenant management as it ensures you access the right data._ parameters: [] /auth/refresh-token: post: summary: Refresh a platform access token operationId: post-auth-refresh-token responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/PlatformTokenResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error description: '' requestBody: content: application/json: schema: type: object properties: refresh_token: type: string description: The refresh token description: '' tags: - Auth security: [] /auth/tenants/authorize: post: summary: Generate platform access token to access a tenant operationId: post-auth-tenants-authorise responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/PlatformTokenResponse' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error description: '' parameters: - in: header name: Authorization schema: type: string format: JWT Token description: The token generated from the API key required: true - in: header name: Capitalise-tenant-id schema: type: string format: uuid description: The tenant id required: true tags: - Auth security: [] /tenants/{tenantId}: patch: summary: Update a tenant reference operationId: patch-tenant requestBody: content: application/json: schema: $ref: '#/components/schemas/TenantsRequest' examples: {} description: A tenant is property or product within a company. tags: - Tenants responses: '200': description: OK '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error security: - Platform access token: [] parameters: [] parameters: - schema: type: string name: tenantId in: path required: true description: The tenant ID to be updated /users: get: summary: Retrieve the list of users in your company tags: - User Manager responses: {} operationId: get-users post: summary: Create a new user to your company operationId: post-users responses: '200': description: OK tags: - User Manager /users/{userId}: parameters: - schema: type: string name: userId in: path required: true get: summary: Retrieve your company's user by ID tags: - User Manager responses: {} operationId: get-users-userId patch: summary: Update your company's user by ID operationId: patch-users-userId responses: '200': description: OK tags: - User Manager servers: - url: /api/platform/v1 components: schemas: OAuth2AuthorizedTokenDto: title: OAuth2AuthorizedTokenDto type: object description: >- (tsType: OAuth2AuthorizedTokenDto, schemaOptions: { exclude: undefined }) properties: access_token: type: string refresh_token: type: string refresh_token_expires_in: type: number scope: type: string expires_in: type: number token_type: type: string additionalProperties: false x-typescript-type: OAuth2AuthorizedTokenDto SignInRequestDto: title: SignInRequestDto type: object properties: email: type: string password: type: string required: - email - password additionalProperties: false SignUpRequestDto: title: SignUpRequestDto type: object properties: type: type: string enum: - BUSINESS - INTRODUCER - LENDER firstName: type: string lastName: type: string email: type: string password: type: string phone: type: string referredBy: type: string terms: type: boolean newsletter: type: boolean countryCode: type: string enum: - ZA - GB required: - type - firstName - lastName - email - company - password - terms - countryCode additionalProperties: false APIKeyAuthorizeRequestDto: title: APIKeyAuthorizeRequestDto type: object properties: apiKey: type: string description: The partner API key minLength: 1 callback: type: string description: Callback to redirect to after partner client login succeeds minLength: 1 required: - apiKey - callback additionalProperties: false AuthorizeThirdPartyResponseDto: title: AuthorizeThirdPartyResponseDto type: object description: >- (tsType: AuthorizeThirdPartyResponseDto, schemaOptions: { exclude: undefined }) properties: url: type: string additionalProperties: false x-typescript-type: AuthorizeThirdPartyResponseDto UserAuthorizeRequestDto: title: UserAuthorizeRequestDto type: object properties: email: type: string description: The user email to authenticate password: type: string description: The user password required: - email - password additionalProperties: false AccessTokenResponseDto: title: AccessTokenResponseDto type: object description: '(tsType: AccessTokenResponseDto, schemaOptions: { exclude: undefined })' properties: jwt: type: string description: Platform API OAuth2 Token (JWT) additionalProperties: false x-typescript-type: AccessTokenResponseDto OldSignUpRequestDto: title: OldSignUpRequestDto type: object properties: name: type: string email: type: string password: type: string companyName: type: string userType: type: string enum: - business - introducer - lender phone: type: string referredBy: type: string terms: type: boolean newsletter: type: boolean companyNumber: type: string introducerType: type: string enum: - ACCOUNTANT - COMMERCIAL_BROKER - PROFESSIONAL_ADVISER - TRADE_ASSOCIATION additionalProperties: false APIKeyResponseDto: title: APIKeyResponseDto type: object description: '(tsType: APIKeyResponseDto, schemaOptions: { exclude: undefined })' properties: key: type: string description: Capitalise API key partnerApiKey: type: string description: Capitalise API key additionalProperties: false x-typescript-type: APIKeyResponseDto APIKeyRequestDto: title: APIKeyRequestDto type: object properties: name: type: string description: A name for the API key partnerApiKey: type: string description: The API key of the Capitalise partner scopes: type: array items: type: string description: The allowed scopes for the API key enum: - profile:multiples - profile:read - profile:write - questionnaire:read - questionnaire:write - funding:read - funding:write - insights:read - scoring:read - offline_access expiresAt: type: string format: date-time description: >- The date your API key will expire. Empty value will generate a permanent token required: - name - scopes additionalProperties: false TenantsResponse: description: '' type: object x-examples: {} title: Tenants response properties: id: type: string minLength: 1 description: Tenant ID example: 40d0dc8e-20ff-4efc-b905-61c236c68c1e referenceId: type: string minLength: 1 description: Unique reference ID provided by you example: CompanyA-9320498 createdDateTime: type: string minLength: 1 format: date-time description: Tenant created date and time example: '2022-04-25T08:49:17.000Z' updatedDateTime: type: string minLength: 1 format: date-time description: Tenant update date and time example: '2022-04-25T08:49:17.000Z' required: - id - createdDateTime - updatedDateTime TenantsRequest: title: Tenants request type: object properties: referenceId: type: string description: >- A unique referenece. Highly recommend not to use personal identifiable information. example: CompanyA-9320498 TenantsResponseGET: description: '' type: object x-examples: The 2nd and 3rd out of total 6 tenants: data: - id: 40d0dc8e-20ff-4efc-b905-61c236c68c1e referenceId: CompanyA-9320498 createdDateTime: '2022-04-19T15:05:14.000Z' updatedDateTime: '2022-04-19T15:05:14.000Z' - id: d6c85eae-de3e-4110-b755-4856d1703a6a referenceId: CompanyE-af83hsi2 createdDateTime: '2022-04-25T08:49:17.000Z' updatedDateTime: '2022-04-25T08:49:17.000Z' links: self: >- http://demo.capitalise.com/api/business/v1/tenants?offset=2&limit=2 prev: >- http://demo.capitalise.com/api/business/v1/tenants?offset=0&limit=2 next: >- http://demo.capitalise.com/api/business/v1/tenants?offset=4&limit=2 meta: totalEntries: 6 title: Tenants response - GET properties: data: type: array uniqueItems: true maxItems: 100 minItems: 0 items: $ref: '#/components/schemas/TenantsResponse' links: type: object required: - self properties: self: type: string minLength: 1 description: The endpoint for this request prev: type: string description: The endpoint for the next batch of tenants next: type: string description: The endpoint for the previous batch of tenants meta: type: object required: - totalEntries properties: totalEntries: type: number description: >- Total count of the tenants regardless of offset and limit filters required: - data - links - meta PlatformTokenResponse: title: PlatformTokenResponse type: object properties: access_token: type: string description: The platform access token example: >- eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6InByb2ZpbGU6bXVsdGlwbGVzIG9mZmxpbmVfYWNjZXNzIiwidXNlck1ldGFkYXRhIjp7fSwiYXBwTWV0YWRhdGEiOnsidXNlciI6eyJpZCI6MTkyMiwiZW1haWwiOiJleGFtcGxlQGFjbWVsaW1pdGVkLmNvbSIsIm5hbWUiOiJFeGFtcGxlIFVzZXIifSwiZW50aXR5Ijp7ImlkIjoxMDIwMiwidHlwZSI6IklOVFJPRFVDRVIiLCJjb3VudHJ5Q29kZSI6IkdCIn0sImFwaUtleVRva2VuSWQiOiI2Mjc5NGM3NjZhYmFjOTZlNjNjYTFlZGNmIiwidHlwZSI6ImVudGl0eSJ9LCJpYXQiOjE2NjA2NDEzOTIsImV4cCI6MTY2MDY3NzM5MiwiaXNzIjoiY2FwaXRhbGlzZSIsImp0aSI6IjQ0M2I3ZDc4LTVmMzctNDdkNC1hY2IzLTQ1MTZjNmM4N2FkNiJ9.EhFWMFuA0k0TdXbM7dJxs8Vw-kQZ315RkOasZL7-ycEUgRPkf_OzIge2Y5ThLKm-sC43IEzP1Lb_UcXUU8-1BNQI5js6gSrWT6lPCG-slb1ApZrSv29LcX6xq9VYvXCmB-tj5UPUcWirG-tPGI8a98E8ZVBFKhYF9-kBj9-CJNXFAAPXmDAhmmSb6BLX6pciTr08wZ5dC77Gw09Zl_TI9fS-Vt2sZ-vbI9TaQh4_Q1uqvzQsQHjMVvBby9eT3DDL4ubOpVh7SGczoBAlQYcppLfjVOOX0fGwOSYePqDo37LLKgKBefFocQh9nssp5RFnIhinWn_bmBio3k17k0ewYg expires_in: type: integer description: The expiry of `access_token` in seconds example: '36000' refresh_token: type: string description: The refresh token example: >- eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6InByb2ZpbGU6bXVsdGlwbGVzIG9mZmxpbmVfYWNjZXNzIiwidXNlck1ldGFkYXRhIjp7fSwiYXBwTWV0YWRhdGEiOnsidXNlciI6eyJpZCI6MTkyMiwiZW1haWwiOiJleGFtcGxlQGFjbWVsaW1pdGVkLmNvbSIsIm5hbWUiOiJFeGFtcGxlIFVzZXIifSwiZW50aXR5Ijp7ImlkIjoxMDIwMiwidHlwZSI6IklOVFJPRFVDRVIiLCJjb3VudHJ5Q29kZSI6IkdCIn0sImFwaUtleVRva2VuSWQiOiI2Mjc5NGM3NjZhYmFjOTZlNjNjYTFlZGNmIiwidHlwZSI6ImVudGl0eSJ9LCJpYXQiOjE2NjA2NDEzOTIsImV4cCI6MTY2MDY3NzM5MiwiaXNzIjoiY2FwaXRhbGlzZSIsImp0aSI6IjQ0M2I3ZDc4LTVmMzctNDdkNC1hY2IzLTQ1MTZjNmM4N2FkNiJ9.I_ZuJD8knx6XU8O1uJyU8fHfPgxAN8uLIX-7bQ1POJbnZD0sYsdxDTdVp5-aAGFouNRe6cbS0IB0hxj1YocI28lYFI6icPbeb0deMqJon562KCyyFflQJN_bLx_9WHvwa0ZireUhEK6MIX2SmCs6k5zqhoKBvj897byfyyZupXtSZnJDzxv4s8Li3rtuAsLZWX3ZiKmkBsat-9RRm2JXL7Ea2jfjAvGUo2Lifty44ktF2l378zxUxKhaUTORpSV48swZhCpOU6eY2BU_oyfQ4i2H6vZISH3fqmZIE5PytlD8twxMyNoaksG0payQICorJBbjohBTl5QKdIw_MIWxHOQ scope: type: string description: The scopes that the platform access token should have example: profile:multiples offline_access token_type: type: string description: The token type example: Bearer description: '' securitySchemes: Platform Access Token: type: http scheme: bearer description: >- Your bearer token should be a platform access token generated from `/platform/v1/auth/authorize` or `/platform/v1/auth/refresh-token` X-API-Key: name: X-API-Key type: apiKey in: header description: >- An API key is a token that you provide when making API calls. Include the token in a header parameter called X-API-Key. Generated by [Platform V1](/api/platform#operation/APIKeyManager.createApiKey) Example: `X-API-Key: 123` Login Access Token: type: http scheme: bearer description: >- The access token generated by `/platform/v1/auth/login` ([generate login token](#tag/Auth/operation/AuthorizationManager.login)), which is specifically used to programmatially generate API key. tags: - name: Auth description: Authorisation services for Capitalise APIs - name: Tenants description: Tenant-based access to Business APIs - name: User Manager description: Managing your users' access in Capitalise.com security: - X-API-Key: [] x-tagGroups: - name: Live tags: - Auth - Tenants - name: Upcoming tags: - User Manager