Fundrise Authentication API

openapi: 3.2.0
info:
  title: Fundrise Connect (External API) Authentication API
  version: 1.0.0
  contact:
    name: Fundrise Connect Support Team
    email: connect@fundrise.com
  description: "### Introduction\nFundrise is a Fintech company democratizing access to alternative assets through technology. This API represents a prototype of Fundrise Connect, which is our external API for providing Client onboarding and investment into our alternative assets. To get started, contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a> or view our <a href='#tag/Authentication'>getting access documentation</a>. <br> <br> The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses,  and uses standard HTTP response codes, authentication, and verbs. <br> <br> Throughout this document, the following terminology will be used:\n  - <strong>Client</strong>: This refers to an End-User or customer that a Partner onboards onto Fundrise for investing in Fundrise assets.\n  - <strong>Partner</strong>: This refers to a company working with Fundrise to provide their End-Users or customers access to Fundrise assets.\n\n### Errors\nFundrise uses conventional HTTP response codes to indicate the success or failure of an API request. In general:\n  - Codes in the 2xx range indicate success. \n  - Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). \n  - Codes in the 5xx range indicate an error with Fundrise's servers (these are rare).\n\nSome 4xx errors that could be handled programmatically (e.g., an address is invalid) include an error code that briefly explains the error reported. These errors that can be handled programmatically have error codes in the error response.  Endpoints that have programmatically resolvable errors have those codes defined in their schema definitions.\n### Request IDs \nEach API request has an associated request identifier. You can find this value in the response headers, under `Request-Id`.  This error will also be present in the error response body under the field `referenceId`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n### Idempotency \nFor some POST endpoints, we require a Partner idempotency key to ensure operations are not duplicated. For both Client creation and Investment placement, we require a `partnerReferenceId` to ensure that Investments and Clients are not duplicated in our system.\n### Versioning\nAPI endpoints are versioned with path versioning. Each endpoint contains a version path parameter e.g. (`/v1/...`). To release new functionality without impacting existing customers, we will version endpoints and increment version numbers accordingly.  <br> <br> When endpoints are staged to be deprecated, Partners will be given ample time to integrate with new versions according to our service agreement. Partners should expect to receive communications related to deprecation timelines. \n### Rate limiting\nWe enforce rate limiting on our public API to avoid DoS (denial of service) issues. This rate limiting is enforced per Client and per HTTP method. If you are running into  rate limiting issues, please contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a>."
  x-logo:
    url: https://d10cq78zmnjvsx.cloudfront.net/interface/logo-hz-color.svg
    backgroundColor: '#FFFFFF'
    altText: Fundrise
    href: .
servers:
- description: Sandbox
  url: https://sandbox.fundrise.com
tags:
- name: Authentication
  description: "### Getting access \nTo get started, please contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a>.\n### Terminology\n  - <strong>Client</strong>: This refers to an End-User or customer that a Partner onboards onto Fundrise for investing in Fundrise assets.\n  - <strong>Partner</strong>: This refers to a company working with Fundrise to provide their End-Users or customers access to Fundrise assets.\n\n### Access issues\nTo ensure a safe, secure platform, Fundrise imposes strict access controls to all APIs. As such, there may be services or capabilities documented that are inaccessible with current permissions.  Contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a> to gain permissions for additional endpoints or to receive customized support for specific issues or concerns.\n### Security Models\nFundrise's API supports two different HTTP security schemes:\n- PartnerBasicAuthentication\n- ClientBearerAuthentication\n\nThe appropriate security scheme per endpoint is identified in the documentation. \nPartnerBasicAuthentication and ClientBearerAuthentication use values that should be treated as sensitive data. Fundrise requires  encrypted storage of these values with necessary controls to limit access. All information returned must be treated in full compliance to the end-user agreements.\n\n#### PartnerBasicAuthentication \nAccess an endpoint using Partner credentials in HTTP Header. \n\n  PartnerBasicAuthentication is enforced by HTTP Basic Authentication. A Partner username and password will be provided by Fundrise support. \n  The Partner password should be stored securely. At a minimum, it should be encrypted at-rest and access restricted to services making requests to the Fundrise API.\n  The Partner password should not be exposed to a Client or any of their devices. If the password is compromised please contact Fundrise support.\n\n\n#### ClientBearerAuthentication \nAccess an endpoint using an OAuth access token associated with a specific Client. \n\n  ClientBearerAuthentication is enforced by HTTP Bearer Authentication and requires an OAuth access token. \n  Since access tokens are scoped to specific Clients, they identify and authenticate the Client in a request.\n\n\n  Access tokens can be obtained in <a href=\"#tag/Authentication/operation/GetAccessToken\">Get Access Token</a> requests by using the refresh token flow.\n  OAuth refresh token are issued on <a href=\"#tag/Clients/operation/CreateClient\">Client Creation</a> and scoped specifically to that Client.\n  The refresh tokens will not expire and should be stored securely after Client creation. At a minimum, refresh tokens should be encrypted at-rest and access restricted to services making requests to the Fundrise API.\n  Refresh tokens should not be exposed to a Client or any of their devices."
paths:
  /v1/oauth/token:
    post:
      summary: Get Access Token
      security:
      - PartnerBasicAuthentication: []
      description: "This endpoint is an OAuth 2.0 Token Endpoint that supports the refresh token flow to obtain active access tokens, which are needed to access secured endpoints with ClientBearerAuthentication. \n\nRefresh tokens are issued on <a href=\"#tag/Clients/operation/CreateClient\">Client Creation</a> and are scoped to that specific Client.  Refresh tokens will not expire and should only be used to obtain new access tokens. Refresh tokens should be stored securely. At a minimum, refresh tokens should be encrypted at-rest and access restricted to services making requests to the Fundrise API. Refresh tokens should not be exposed to a Client or any of their devices.\n\nAccess tokens have a limited lifespan, which is indicated in the `expiresIn` attribute of the response. When an access token expires, obtain a new access token using this endpoint. Access tokens will be scoped to the specific Client that the refresh token was scoped to.\n\nNote, the refresh token will be returned in the response along with the access token. Since refresh tokens will not expire, this should be the same refresh token that was used in the request."
      tags:
      - Authentication
      operationId: GetAccessToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grantType:
                  type: string
                  description: OAuth Grant Type must be `refresh_token`.
                  x-field-extra-annotation: '@NotBlank'
                refreshToken:
                  type: string
                  description: The refresh token value.
                  x-field-extra-annotation: '@NotBlank'
              required:
              - grantType
              - refreshToken
            examples:
              Refresh:
                value:
                  grantType: refresh_token
                  refreshToken: a1929bbf-acb1-430f-a87f-9b79a8cff1f4
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuth2AccessTokenResponse'
        '400':
          description: Invalid operation type, Improperly formatted fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                Invalid grant type:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c35
                    message: Invalid grant type
                Missing refresh token:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c35
                    validationErrors:
                      refreshToken:
                      - must not be blank
                      - must not be null
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    FundriseConnectError:
      title: Error object
      description: Error from Fundrise Connect.
      type: object
      properties:
        referenceId:
          description: A unique reference ID generated for every request that is for error tracing.
          maxLength: 1000
          type: string
        code:
          description: A numeric code mapping to a specific validation error.
          maxLength: 6
          type: string
        message:
          description: A human readable description of the error.
          maxLength: 1000
          type: string
        validationErrors:
          description: A map of field names to an array of form validation error messages
          $ref: '#/components/schemas/FieldErrorMap'
      required:
      - referenceId
    FieldErrorMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/StringArray'
    OAuth2AccessTokenResponse:
      description: Contains information needed to leverage the Client Bearer Authentication security scheme. Values are sensitive and allow api calls on behalf of a specific Client. The access token is to  be used in subsequent API calls protected by the Client Bearer Authentication schema. The access token is for individual Clients, and usage of the same token for multiple  Clients will cause unintended actions within our API.
      properties:
        accessToken:
          description: The access token.
          type: string
          example: HgHaJimFLx5WbPTWwvrw4ktJApo
        refreshToken:
          description: The refresh token.
          type: string
          example: HnGMTF2gVKQU-7IrCwhlXEEU0EY
        scope:
          description: The scopes granted to the access token.
          type: string
          example: PARTNER:READ PARTNER:WRITE
        tokenType:
          description: The token type, which will be "Bearer".
          type: string
          example: Bearer
        expiresIn:
          description: The amount of time in seconds until the access token expires.
          type: string
          format: int64
          example: '3598'
    StringArray:
      type: array
      items:
        type: string
  responses:
    '403':
      description: Customer is not permitted to access the resource
    '500':
      description: Internal Service Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FundriseConnectError'
          examples:
            clientExists:
              value:
                referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c35
                message: Internal service error
    '401':
      description: Unauthorized request to server, Invalid access token or Partner credentials
  securitySchemes:
    PartnerBasicAuthentication:
      description: PartnerBasicAuthentication is enforced by HTTP Basic Authentication. A Partner username and password will be provided by Fundrise support.  The Partner password should be stored securely. At a minimum, it should be encrypted at-rest and access restricted to services making requests to the Fundrise API. The Partner password should not be exposed to a Client or any of their devices. If the password is compromised please contact Fundrise support.
      type: http
      scheme: basic
    ClientBearerAuthentication:
      description: 'ClientBearerAuthentication is enforced by HTTP Bearer Authentication and requires an OAuth access token.  Since access tokens are scoped to specific Clients, they identify and authenticate the Client in a request.


        Access tokens can be obtained in <a href="#tag/Authentication/operation/GetAccessToken">Get Access Token</a> requests by using the refresh token flow. OAuth refresh token are issued on <a href="#tag/Clients/operation/CreateClient">Client Creation</a> and scoped specifically to that Client. The refresh tokens will not expire and should be stored securely after Client creation. At a minimum, refresh tokens should be encrypted at-rest and access restricted to services making requests to the Fundrise API. Refresh tokens should not be exposed to a Client or any of their devices.'
      type: http
      scheme: bearer