openapi: 3.0.1
info:
  title: Bamboo Account Management Authentication API
  version: ''
  description: "Account creation enables users to invest on Bamboo. Ensure KYC has been completed and each user’s identity verified before creating a brokerage account.\n\n**Best Practice:** To avoid maintenance fees on inactive accounts, create and fund brokerage accounts **only when users initiate their first trade**. You may collect account details in advance but delay sending the request until they’re ready to buy.\n\n##### Prerequisites\n- **Minimum Age:** 18 years (verified via government-issued ID)\n- **Compliance:** Must meet local investment regulations\n\n##### Document Requirements\n<table>\n  <thead>\n    <tr>\n      <th>Country</th>\n      <th>Primary ID</th>\n      <th>Image Requirements</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>Nigeria</th>\n      <td>BVN</td>\n      <td>Passport photo</td>\n    </tr>\n    <tr>\n      <th>Ghana</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n    <tr>\n      <th>South Africa</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n  </tbody>\n</table>\n\n**Note:** Images must be in Base64 format. The `front_id_image` and `back_id_image` fields apply only to Ghana and South Africa.\n\n##### Phone Number Format\n- Must be in international format (e.g., +2347083864023)\n- Country code must match user’s residence\n- Used for notifications and account security\n"
servers:
- url: https://powered-by-bamboo-sandbox.investbamboo.com
tags:
- name: Authentication
  description: "Before you start making requests, you’ll need to generate an access token. Every request to the API must be authenticated using access tokens and user context headers — this ensures secure and authorized access to your resources.\n\nHere are a few quick tips to help you integrate smoothly and keep your tokens active:\n  - **x-client-token:** A tenant-level access token that expires after 24 hours. You can generate up to 3 tokens per hour.\n- **Refresh Strategy:** Generate a new token before the current one expires to keep your requests running without interruption.\n\nEach endpoint’s required headers are outlined throughout this documentation, so you always know what’s needed to make a successful call.\n"
paths:
  /oauth/token:
    post:
      tags:
      - Authentication
      summary: Generate Access Token
      description: "This endpoint generates your access token, referred to as your `x-client-token` within Bamboo’s system. \nThe credentials needed to generate it will be provided by the Bamboo Team during account setup. \n"
      operationId: Web.Api.AuthController.oauth
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        required: true
        schema:
          type: string
          default: application/json
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        required: true
        schema:
          type: string
          default: en
      - name: app-key
        in: header
        description: Application key that uniquely identifies a tenant as an API consumer.
        example: 1755d3dd-e6b9-4df1-9537-eb9017da70g9
        required: true
        schema:
          type: string
      requestBody:
        description: Tenant Level Authentication Request
        content:
          application/json:
            schema:
              title: Tenant login request
              required:
              - username
              - password
              type: object
              properties:
                username:
                  type: string
                  description: Username
                  example: invest-bamboo
                password:
                  type: string
                  description: Password
                  example: 32qC6I2U5J-0i73zJDEdapFJvwICJAl1I7ScekqupVfouiAMz_J7obWHI3kuDVOL
              description: POST request body parameters
      responses:
        '200':
          description: Tenant Login Successful
          content:
            application/json:
              schema:
                title: Response
                required:
                - access_token
                - expires_in
                type: object
                properties:
                  access_token:
                    type: string
                    required:
                    - access_token
                    description: Tenant access token (x-client-token)
                    example: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikx6aTZoUVRwc2gtS21BNjdzbXdCWiJ9.

                      eyJodHRwczovL2V4YW1wbGUuY29tL2NsYWltIjoiYmFyIiwiaXNzIjoiaHR0cHM6Ly9pbnZlc3RiYW1ib28uYXV0aDAuY29tLyIsInN1YiI6IjZWdUVjV1NFdUZWdGRJM1ExYlliRVV6UGZOVHljTkM4QGNsaWVudHMiLCJhdWQiOiJodHRwczovL3Bvd2VyZWQtYnktYmFtYm9vLXNhbmRib3guaW52ZXN0YmFtYm9vLmNvbS8iLCJpYXQiOjE3NTk1MDU1MzQsImV4cCI6MTc1OTU5MTkzNCwic2NvcGUiOiJyZWFkOmJhbWJvb19kYXRhIGV4dHJhIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwiYXpwIjoiNlZ1RWNXU0V1RlZ0ZEkzUTFiWWJFVXpQZk5UeWNOQzgifQ.

                      F-bR5wEFxtD-3Y93Lzjfi2UY_9V9k8ckGkndhnLa-SXjp9GvitG79MSyUaNahvT6TVmFUw6Us59GhQAltlcETPoBk3wF934FbfGyofAPzsJ6j2mLIHY2YH-l4KO7_ZA9KAPeh8lGN24R5ZMLuDFGjbteNcHp_rCba1KhTYA_EJIL8p2zYsfYn72PAMb0pWUb5v9YC_HYNf95Q5bNHp0W0m7ZI21VwPVD0TRAazT931xCkF4d0oukvEmGkZ0ns8u1VxsZ0b2nUzV0K1YL6nBn68lg8b7lX7tLMReGUCxE_qsfI1vr0WYvQxCrmvjUsMFrDvW5oDlASa25WOcxYDWweQ

                      '
                  expires_in:
                    type: string
                    description: Token expiration time in seconds
                    example: 86400
                description: Result of POST request on tenant login
        '401':
          description: Invalid app key supplied
          content:
            application/json:
              schema:
                title: Unauthorized response
                required:
                - message
                type: object
                properties:
                  message:
                    type: string
                    description: Unauthorized/Invalid Token
                    example: Invalid app key supplied
                description: Token is invalid or has expired
        '422':
          description: Incorrect Parameters
          content:
            application/json:
              schema:
                title: Error changeset response
                required:
                - errors
                - message
                type: object
                properties:
                  message:
                    type: string
                    required: true
                    description: Message why request didn't succeed
                    example: Wrong username or password
                description: Error response for request which manipulates data
      x-codegen-request-body-name: body
x-logo:
  url: bamboo-logo.png
  altText: bamboo logo
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
  - Account Management
- name: Money Movement
  tags:
  - Overview
  - Deposits
  - Withdrawals
- name: US Brokerage Services
  tags:
  - Portfolio Reporting
  - US Securities
  - US Stock Trading
  - US Stock Events
- name: Utilities
  tags:
  - Dictionaries
  - Market Activity
  - Exchange Rate
  - Featured Themes
  - Financial Documents