# ibee | Documentation > This file contains the full content of every public page of https://ibee.ai/docs. The index-only variant is https://ibee.ai/docs/llms.txt; append `.md` to any page URL for that page alone. --- title: Infrastructure, engineered for builders. url: https://ibee.ai/docs last_updated: 2026-10-27 --- # Infrastructure, engineered for builders. #### Resources Everything you need to learn, build, and stay up to date. → [Docs](/docs) → [API Reference](/docs/api-reference/introduction) → [Changelog](/docs/changelog) #### Quick start Get up and running on IBEE Solutions in minutes. → [Sign up](/docs/getting-started/account-setup/sign-up) → [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) #### Build with the API Automate everything — from a single VM to a full deployment pipeline. → [API reference](/docs/api-reference/introduction) → [Authentication](/docs/api-reference/authentication) → [Rate limits](/docs/api-reference/rate-limits) ## Build with IBEE #### [Cloud VMs](/docs/infrastructure/cloud-vms) General-purpose virtual machines. #### [GPU VMs](/docs/infrastructure/gpu-vms) AI/ML and graphics workloads on GPUs. #### [Object Storage](/docs/infrastructure/object-storage) S3-compatible storage for any object. #### [Block Storage](/docs/infrastructure/block-storage) Persistent volumes you can attach to VMs. #### [Bare Metal Servers](/docs/infrastructure/bare-metal) Dedicated physical servers with full hardware access. #### [Load Balancer](/docs/network-security/load-balancer) Distribute traffic across backends with L4 and L7 balancing. #### [CDN](/docs/network-security/cdn) Cache buckets or any HTTPS origin at the edge. #### [Secret Manager](/docs/tools/secret-manager) Versioned secrets with AppRole and Kubernetes access. ## Quick links #### [API reference](/docs/api-reference/introduction) Endpoints, parameters, and example requests. #### [Changelog](/docs/changelog) What's new and recently shipped. #### [Pricing](https://ibee.ai/pricing) Pay only for what you use. #### [Support](/docs/support) Talk to our team — chat, email, or open a ticket. ## From the IBEE team #### [From our blog](https://ibee.ai/blogs) Product updates, deep dives, and engineering posts. #### [Contact sales](https://ibee.ai/company/contact-us) Talk to us about enterprise plans. --- title: Sign Up url: https://ibee.ai/docs/getting-started/account-setup/sign-up description: Create your IBEE Solutions account — register with your email, verify it, set a password, and log in to the portal. last_updated: 2026-09-28 --- # Sign Up > Create your IBEE Solutions account — register with your email, verify it, set a password, and log in to the portal. Create your IBEE Solutions account in four steps: register your email, verify it, set a password, and log in. The process takes under five minutes. ## Before you begin * A valid email address you can access within 24 hours > **Info** > > If you already have an account, click **Log in** at the bottom of the signup form. ### 1. Register your email Go to [portal.ibee.ai/signup](https://portal.ibee.ai/signup). 1. Enter your **Email** address. 2. Check **I agree to the Terms of Use**. The form also links to the Privacy Policy, which explains how IBEE uses your information. 3. Click **Sign up**. The portal confirms that a verification link was sent to your email address. ### 2. Check your inbox > **Warning** > > The verification link expires in **24 hours**. If you open an expired link, the portal shows a **Resend Verification Email** option, or a **Back to Sign Up** button if a new link can't be sent for that address. Open the email from `noreply@ibee.ai` with the subject **Verify your email address**. ### 3. Verify your email and set a password Click **Verify Email** in the email. The **Set Your Password** page opens with your account email already filled in. 1. Enter a **Password** that meets every rule below. 2. Re-enter the same value in **Confirm Password**. 3. Click **Set Password**. | Password rule | Requirement | | ----------------- | ---------------------------------------------------------- | | Length | 12–20 characters | | Uppercase | At least one uppercase letter | | Lowercase | At least one lowercase letter | | Number | At least one number | | Special character | At least one special character (for example `!`, `@`, `#`) | The form checks each rule as you type. After the password is saved, the portal returns you to the login page. ### 4. Log in Go to [portal.ibee.ai](https://portal.ibee.ai). 1. Enter your **Email** and **Password**. 2. Complete the **Cloudflare** security check if it appears. 3. Click **Log in**. If you have turned on [two-factor authentication](/docs/getting-started/account-setup/account-security#two-factor-authentication), the portal then asks for the 6-digit **2FA Code** from your authenticator app. Click **Verify & Log in**. After your first login, you land on the **Organizations** page. It shows any pending invitations to join other organizations and a **Create New Organization** button. See [Create an organization](/docs/getting-started/account-setup/create-an-organization). ## Troubleshooting **Verification email not received** Check your spam folder. The sender is `noreply@ibee.ai`. If the email does not arrive after a few minutes, return to `portal.ibee.ai/signup` and sign up again with the same address. **Verification link expired** Open the expired link. Enter your email address under **Resend Verification Email** to get a new link. If that option isn't shown, click **Back to Sign Up** and register again with the same address. **Password rejected** Check every password rule in the table above. Passwords longer than 20 characters are not accepted, so a long passphrase pasted from a password manager can be rejected. **Forgot your password** Click **Forgot password?** on the login page. See [Account security](/docs/getting-started/account-setup/account-security#reset-a-forgotten-password). **Security check not loading on login** Disable browser extensions that block Cloudflare scripts and reload the page. ## Related pages * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Account security](/docs/getting-started/account-setup/account-security) * [Verify your identity](/docs/getting-started/account-setup/verify-your-identity) * [Restricted countries](/docs/getting-started/account-setup/restricted-countries) --- title: Create an Organization url: https://ibee.ai/docs/getting-started/account-setup/create-an-organization description: Create an IBEE Solutions organization to manage resources, billing, and team members. Learn about country restrictions, geo-detection, currency assignment, tax invoices, and GST verification for Indian businesses. last_updated: 2026-10-27 --- # Create an Organization > Create an IBEE Solutions organization to manage resources, billing, and team members. Learn about country restrictions, geo-detection, currency assignment, tax invoices, and GST verification for Indian businesses. An organization is a billing and resource boundary in IBEE Solutions. Each organization has its own wallet, team members, and workspaces. You can create multiple organizations under a single login — up to **3 owned organizations** by default. See [Organization limits](/docs/platform-fundamentals/limits-and-quotas#organization-limits). ## Before you begin * A signed-in IBEE Solutions account ([Sign up](/docs/getting-started/account-setup/sign-up) if you haven't already) * Your billing address (street, city, postal code, and country) > **Info** > > IBEE Solutions is available in [26 serving countries](/docs/getting-started/account-setup/restricted-countries#serving-countries). Services are not offered in [46 restricted countries](/docs/getting-started/account-setup/restricted-countries) due to U.S. export-control regulations. ## Country detection When you open the organization creation form, the portal detects your country automatically using Cloudflare geo-detection. Three outcomes are possible: | Detection result | What happens | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Serving country** | Your country is pre-filled in the form. Currency and tax type are set automatically. | | **Restricted country** | A red banner appears: *"Services not available in \{country}."* You can still select a different country if your registered business is in a supported region. | | **Other country** | An amber banner appears: *"We don't currently serve \{country}."* Pick a supported country where you have a registered entity, or [contact sales](mailto:sales@ibee.ai). | ## Currency and tax assignment Currency and tax type are set automatically based on your selected country: | Country | Currency | Tax type | | --------------------------- | ------------------ | --------- | | India | INR (Indian Rupee) | GST | | United States | USD (US Dollar) | Sales Tax | | All other serving countries | USD (US Dollar) | VAT | Currency is locked to your country and cannot be changed in the form. If you need a different currency, click **Request a change** below the currency field to submit a currency change request with supporting documents. ### 1. Go to organization setup **First-time users:** After your first login you land on the **Organizations** page. Click **Create New Organization**. **Existing users:** Do one of the following: * On the **Organizations** page, click **Create Organization** in the top right. * Open the organization switcher in the top bar and click **New Organization**. If you already own the maximum number of organizations, the **Create Organization** button is hidden and the portal takes you to the [limit increase request](/docs/platform-fundamentals/limits-and-quotas#request-more-organizations) instead. ### 2. Fill in Organization Details | Field | Required | Notes | | ----------------- | ---------------- | ---------------------------------------------------------------------- | | Organization Name | Yes | A nickname for your reference — shown in your organization list | | Organization Type | Yes | **Business** (default) or **Individual** | | Business Name | Yes (Business) | Legal entity name, used on invoices. Auto-filled from GST if verified. | | Full Name | Yes (Individual) | Your full name as on government ID, used on invoices | ### 3. Fill in Billing Address | Field | Required | | --------------- | -------- | | Street Address | Yes | | Apartment/Suite | No | | City | Yes | | State/Region | No | | Postal Code | Yes | | Country | Yes | The **Country** dropdown only lists the 26 serving countries. Selecting a country automatically sets the currency and tax type. ### 4. Tax Information and Create Check **I want a tax invoice** if you require GST, VAT, or sales tax invoices for this organization. A tax ID field appears for your country, and you must verify it before **Create Organization** is enabled. #### GST verification (India) For organizations in India, the field is **GST Identification Number (GSTIN)**: 1. Enter your 15-character GSTIN (auto-uppercased). 2. Click **Verify GST**. 3. The portal verifies the GSTIN against government records and shows a confirmation dialog with: * Company name, GSTIN, status, registration date, business type, and taxpayer type * Registered address from GST records 4. Click **Apply Details and Create Organization** to auto-fill the business name and address from GST records and create the organization in one step. #### Tax ID validation (other countries) For other serving countries, enter your tax ID and click **Validate** (the button shows the ID type, for example **Validate EIN**). The portal checks the format for your country: | Country | Tax ID field | | ----------------------- | ------------------------------------ | | United States | Employer Identification Number (EIN) | | Australia | Australian Business Number (ABN) | | Canada | Business Number (BN) | | Singapore | Unique Entity Number (UEN) | | United Kingdom | VAT Registration Number | | United Arab Emirates | Tax Registration Number (TRN) | | Other serving countries | VAT or tax identification number | Click **Change** to edit a validated ID. When all required fields are complete, click **Create Organization**. ## After creation The portal opens the new organization's **Workspaces** page. Every new organization starts with three workspaces — **production**, **dev**, and **stage** — which count toward the limit of 5 workspaces per organization. See [Dashboard & navigation](/docs/getting-started/overview/dashboard-navigation#workspaces-page). If you haven't verified your identity yet, a banner prompts you to complete KYC. Click **Complete KYC** to [verify your identity](/docs/getting-started/account-setup/verify-your-identity). Full access to deploy servers and use all cloud services requires completed identity verification. To change the organization's name, address, or tax details later, see [Organization settings](/docs/platform-fundamentals/organization-settings). ## Troubleshooting **Create button is disabled** Ensure all required fields are filled. If you checked **I want a tax invoice**, verify your GSTIN (India) or validate your tax ID (other countries) first. **Create Organization button is missing** You own the maximum number of organizations. [Request more organizations](/docs/platform-fundamentals/limits-and-quotas#request-more-organizations). **Country not in the dropdown** Only the 26 serving countries appear in the dropdown. See the [restricted countries](/docs/getting-started/account-setup/restricted-countries) page for the full list. **Red banner: "Services not available"** You are in a restricted country. If you have a registered business in a supported country, select that country manually. Otherwise, [contact sales](mailto:sales@ibee.ai). **Currency shows wrong value** Currency is determined by your country: India uses INR, all others use USD. To request a different currency, click the **Request a change** link below the currency field. **GST verification failed** Ensure you are entering a valid, active 15-character GSTIN. Inactive or cancelled GSTINs are rejected. ## Related pages * [Restricted countries](/docs/getting-started/account-setup/restricted-countries) * [Verify your identity](/docs/getting-started/account-setup/verify-your-identity) * [Add billing](/docs/getting-started/account-setup/add-billing) * [Organization settings](/docs/platform-fundamentals/organization-settings) * [Organizations and tenancy model](/docs/platform-fundamentals/organizations-and-tenancy-model) --- title: Restricted Countries url: https://ibee.ai/docs/getting-started/account-setup/restricted-countries description: IBEE Solutions does not offer services in certain countries due to U.S. export-control and trade-sanction regulations. Review the full list of restricted countries and the 26 countries where IBEE Solutions operates. last_updated: 2026-10-27 --- # Restricted Countries > IBEE Solutions does not offer services in certain countries due to U.S. export-control and trade-sanction regulations. Review the full list of restricted countries and the 26 countries where IBEE Solutions operates. IBEE Solutions complies with U.S. Department of Commerce and Office of Foreign Assets Control (OFAC) trade and export-control regulations. As a result, services are **not available** in certain countries and territories. When you create an organization, the portal detects your location automatically. If you are in a restricted country, a banner explains that services are unavailable in your region. > **Warning** > > **Important Notice** > > Users located in restricted countries cannot create an IBEE Solutions organization or deploy resources. If your registered business is in a supported country, you can select that country manually during organization setup. For questions, contact [sales@ibee.ai](mailto:sales@ibee.ai). ## Restricted countries The following 46 countries and territories are restricted under U.S. export-control and OFAC sanctions regulations: | # | Country | | -- | -------------------------------- | | 1 | Afghanistan | | 2 | Armenia | | 3 | Azerbaijan | | 4 | Bahrain | | 5 | Belarus | | 6 | Cambodia | | 7 | Central African Republic | | 8 | China | | 9 | Cuba | | 10 | Democratic Republic of the Congo | | 11 | Egypt | | 12 | Eritrea | | 13 | Georgia | | 14 | Haiti | | 15 | Hong Kong | | 16 | Iran | | 17 | Iraq | | 18 | Jordan | | 19 | Kazakhstan | | 20 | Kuwait | | 21 | Kyrgyzstan | | 22 | Laos | | 23 | Lebanon | | 24 | Libya | | 25 | Macau | | 26 | Moldova | | 27 | Mongolia | | 28 | Myanmar | | 29 | Nicaragua | | 30 | North Korea | | 31 | Oman | | 32 | Pakistan | | 33 | Qatar | | 34 | Russia | | 35 | Saudi Arabia | | 36 | Somalia | | 37 | South Sudan | | 38 | Sudan | | 39 | Syria | | 40 | Tajikistan | | 41 | Turkmenistan | | 42 | Uzbekistan | | 43 | Venezuela | | 44 | Vietnam | | 45 | Yemen | | 46 | Zimbabwe | ## Why are these countries restricted? IBEE Solutions is subject to U.S. trade and export-control laws, including regulations administered by the U.S. Department of Commerce Bureau of Industry and Security (BIS) and the U.S. Department of the Treasury Office of Foreign Assets Control (OFAC). These laws restrict the provision of cloud computing and infrastructure services to individuals and entities in sanctioned or embargoed countries and territories. ## Serving countries IBEE Solutions currently operates in the following 26 countries: | Region | Countries | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Asia-Pacific** | Australia, India, Israel, Malaysia, Singapore | | **Europe** | Austria, Belgium, Cyprus, Denmark, Finland, France, Germany, Italy, Latvia, Netherlands, Norway, Portugal, Spain, Sweden, Switzerland, United Kingdom | | **Middle East** | Turkey, United Arab Emirates | | **Americas** | Canada, Costa Rica, United States | If your country is not listed above and is not restricted, you may still be able to use IBEE Solutions. Select a supported country where you have a registered business entity during organization creation, or [contact sales](mailto:sales@ibee.ai) to discuss availability in your region. ## Related pages * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Sign up](/docs/getting-started/account-setup/sign-up) --- title: Verify Your Identity url: https://ibee.ai/docs/getting-started/account-setup/verify-your-identity description: Complete identity verification (KYC) to unlock all IBEE Solutions services. Indian users verify with Aadhaar via Digilocker. International users verify with a government-issued ID and selfie. last_updated: 2026-09-28 --- # Verify Your Identity > Complete identity verification (KYC) to unlock all IBEE Solutions services. Indian users verify with Aadhaar via Digilocker. International users verify with a government-issued ID and selfie. Identity verification (KYC) is done at the **user level** — once you verify your identity, all your organizations are unlocked. Only identity verification is required; no business or GST verification is needed. The process takes about two to three minutes. > **Info** > > You must complete identity verification to deploy servers, create API tokens, and access all IBEE Solutions services. ## Before you begin * A signed-in IBEE Solutions account ([Sign up](/docs/getting-started/account-setup/sign-up) if you haven't already) * **India:** your 12-digit Aadhaar number and a mobile number linked to Aadhaar (for OTP) * **International:** a government-issued photo ID (driver's license, passport, or national ID) and a device with a camera for a selfie ## Verification methods | Method | Who should use it | What you need | Time | | ----------------- | ------------------ | ----------------------------- | ----------- | | **India** | Residents of India | Aadhaar number + OTP | \~2 minutes | | **International** | Everyone else | Government-issued ID + selfie | \~3 minutes | IBEE detects your country automatically and marks the suggested method as **Detected**. Select the other method if the detection is wrong. ### 1. Start verification Navigate to [portal.ibee.ai/verify](https://portal.ibee.ai/verify). Click **Start Verification**. The **Complete KYC** dialog opens with two options: | Option | Label | Method | | ----------------- | -------------------------------------- | ------------------------------------ | | **India** | Verify with your **Aadhaar** | Aadhaar via Digilocker (\~2 minutes) | | **International** | Verify with **government ID + selfie** | ID scan + selfie (\~3 minutes) | Select the option that matches your country of residence. ### 2a. Verify with Aadhaar (India) 1. Click **Verify with Aadhaar**. 2. Complete Aadhaar verification through **Digilocker** — authorize document sharing and enter the OTP sent to your Aadhaar-linked mobile number. 3. On success, the portal shows **Verification complete** and takes you back to the page you started from, or to your organization. ### 2b. Verify with Government ID (International) 1. Click **Verify with ID**. 2. Review the privacy notice and click **Agree and continue**. 3. Continue on your current device, or scan the QR code to use your phone's camera. 4. Scan the front of your driver's license, passport, or government-issued photo ID. 5. Take a selfie when prompted to confirm the ID belongs to you. 6. On success, the portal shows **Verification complete** and takes you back to the page you started from, or to your organization. Once verified, your account has full access to all IBEE Solutions services across all your organizations, including VM deployment, GPU VMs, block storage, and API token creation. ## Troubleshooting **Verification prompt not appearing** Navigate directly to `portal.ibee.ai/verify`. If you are already verified, you are redirected to your organizations. **Wrong country detected** The verification modal suggests a method based on your location. If the **Detected** badge is on the wrong option, select the other one. **DigiLocker not loading** Ensure your browser allows redirects and pop-ups for `portal.ibee.ai`. Try a different browser if the issue persists. **Aadhaar number rejected** Enter your 12-digit Aadhaar number without spaces. **No document detected during ID scan (International)** Position your government-issued photo ID flat and in good lighting. Choose **Retake photo** to try again. **Verification submitted but status not updated** The portal polls for up to 60 seconds after submission. If your status does not update, refresh the page — verification may take a moment to propagate. ## Related pages * [Sign up](/docs/getting-started/account-setup/sign-up) * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Add billing](/docs/getting-started/account-setup/add-billing) --- title: Account Security url: https://ibee.ai/docs/getting-started/account-setup/account-security description: Protect your IBEE Solutions login — turn on two-factor authentication with an authenticator app, change your password, review your login history, and reset a forgotten password. last_updated: 2026-10-19 --- # Account Security > Protect your IBEE Solutions login — turn on two-factor authentication with an authenticator app, change your password, review your login history, and reset a forgotten password. Your login is personal: it is the same across every organization you own or belong to. Two-factor authentication (2FA), your password, and your login history are managed from your user profile, not from an organization's settings. ## Open your security settings 1. Click your **avatar** in the top-right corner of the portal. 2. Click **View Profile**. The **User Settings** page opens. The **Security** section contains **Two-Factor Authentication**, **Password**, and **Login History**. ## Edit your profile The **Basic Information** section on **User Settings** shows your **Full Name**, **Display Name**, **Email**, and **Phone**. Click **Edit**, change the fields, and click **Save**. **Full Name** and **Phone** (with country code) are required. Your email address cannot be changed here. ## Two-factor authentication With 2FA turned on, every login needs your password **and** a 6-digit code from an authenticator app on your phone. 2FA is off until you turn it on. ### Turn on 2FA ### Install an authenticator app Install an authenticator app on your phone — for example Google Authenticator, Authy, or Microsoft Authenticator. ### Start setup In **Security → Two-Factor Authentication**, click **Enable Two-Factor Authentication**. ### Confirm your password Enter your current password under **Enter Your Password to Continue** and click **Continue**. ### Scan the QR code Open your authenticator app and scan the QR code. If you can't scan it, copy the setup key shown under **Can't scan? Enter this key manually** into the app. > **Warning** > > Save the QR code or setup key somewhere secure. You need it to set up the authenticator again if you lose access to your app. ### Enter a code Type the current 6-digit code from the app into **Enter the 6-digit Code from Your App** and click **Enable 2FA**. The code changes every 30 seconds. The status badge changes to **Enabled**. ### Log in with 2FA After you enter your email and password on the login page, the portal shows **Two-Factor Authentication** and asks for your **2FA Code**. Enter the 6-digit code from your authenticator app and click **Verify & Log in**. ### Turn off 2FA 1. In **Security → Two-Factor Authentication**, click **Disable 2FA**. 2. Enter your current password. 3. Confirm with **Disable 2FA**. After 2FA is off, you only need your password to log in. ## Change your password 1. In **Security → Password**, click **Change Password**. 2. Enter your **Current Password**. 3. Enter a **New Password**. It must meet the same rules as when you signed up: 12–20 characters with at least one uppercase letter, one lowercase letter, one number, and one special character. 4. Click **Update Password**. ## Login history **Security → Login History** lists your recent login attempts: | Column | Description | | --------------- | ------------------------------------ | | **Date & Time** | When the login was attempted | | **IP Address** | The IP address the attempt came from | | **Status** | **Successful** or **Failed** | If you see a login you don't recognize, change your password right away and turn on 2FA. ## Reset a forgotten password ### Request a reset link On the login page, click **Forgot password?**. Enter your **Email** and click **Send Reset Link**. If an account exists for that address, a password reset link is sent to it. ### Set a new password Open the link from the email. On **Set Your Password**, enter a new **Password**, confirm it in **Confirm Password**, and click **Set Password**. The password rules are the same as at [sign-up](/docs/getting-started/account-setup/sign-up). ### Log in The portal returns you to the login page. Log in with your new password. If the reset link has expired, the page shows **Request a new reset link**. Click it to start again. ## Related pages * [Sign up](/docs/getting-started/account-setup/sign-up) * [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles) * [API Tokens](/docs/tools/api-tokens) --- title: Add Billing url: https://ibee.ai/docs/getting-started/account-setup/add-billing description: Set up billing for your IBEE Solutions organization — purchase prepaid credits (online payment in India, card in other countries), redeem promo codes, save a card, upload TDS certificates, and apply for Invoice Billing. last_updated: 2026-10-27 --- # Add Billing > Set up billing for your IBEE Solutions organization — purchase prepaid credits (online payment in India, card in other countries), redeem promo codes, save a card, upload TDS certificates, and apply for Invoice Billing. New IBEE Solutions organizations are billed from a **prepaid wallet**: you add credits, and usage is deducted as resources run. The platform checks your billing state before every resource creation. If your balance does not cover the resource, a **Billing needs attention** popup asks you to add credits. How you pay depends on your organization's currency: * **India (INR):** Online payment (UPI, cards, or net banking). * **International (USD):** Credit or debit card. You can save cards on the organization for future purchases. Organizations that qualify can later switch to monthly **Invoice Billing** instead of prepaid credits: usage is billed in arrears within an approved credit limit. See [Apply for Invoice Billing](#apply-for-invoice-billing). ## Before you begin * An IBEE Solutions organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)) * A verified identity ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)) * The **Admin** or **Billing** role in the organization ## Purchase credits ### Open Payment Method In the portal sidebar, click **Payment Method** under **Billing**. You can also click **Add Credits** in any **Billing needs attention** popup — it opens this page with the purchase dialog already open. ### Start a purchase In **Credits & Spend Management**, click **Purchase credits** on the **Purchased credits** card. ### Choose how to pay (India only) Indian organizations choose **Online payment** (UPI, cards, or net banking; credited instantly) and click **Continue**. ### Choose an amount Pick a preset amount or enter your own. The dialog checks the amount against the minimum and maximum for one purchase in your currency. ### Pay Click **Continue** (India) or **Continue to payment** (international), then complete the payment. International organizations can pick a saved card or **New card**, then click **Pay**. When the payment succeeds, the portal confirms it; your wallet updates shortly after. > **Info** > > Indian organizations must make a first purchase before creating their first resource. The **Billing needs attention** popup shows the minimum amount. ## Redeem a promo code 1. On **Payment Method**, click **Redeem promo code** on the **Promo balance** card. 2. Enter the code and click **Apply**. Promo credits are used before purchased credits, may be applied automatically to open invoices, and unused promo credits may expire. ## Save a card (international) Organizations outside India can save cards in the **Payment Methods** section of the **Payment Method** page: 1. Click **Add Card**. In **Add Payment Card**, select the consent checkbox and click **Save Card**, then enter your card details. A temporary card validation charge is made and refunded automatically once the card is verified. 2. Click **Set Default** on a card to use it by default. 3. To delete a card, click its **Remove Card** (trash) icon, then **Remove**. Saved cards belong to the organization. ## Wallet balance The **Payment Method** page shows two balances in **Credits & Spend Management**: | Card | What it holds | | --------------------- | ------------------------------------------------------------------------------------------------- | | **Promo balance** | Promotional credits (used first) | | **Purchased credits** | Credits you bought. Shows **Amount due** instead of **Available** when the balance is below zero. | Expand **Recent wallet activity** to see the latest credits and debits (**When**, **Activity**, **Reference**, **Amount**). Click **View all** for the full list: credits are positive, and invoice and usage debits are negative. > **Warning** > > If your wallet balance does not cover a new resource, the platform blocks the creation. Existing resources continue running, but you must add credits before deploying anything new. ## Upload a TDS certificate (India) Indian organizations that deduct TDS can submit Form 16A in the **TDS certificates** section of **Payment Method**: 1. Click **Upload Form 16A**. 2. Choose the **Financial year** and **Quarter**, and select the **Form 16A PDF** (PDF up to 10 MB). 3. Click **Submit**. Each certificate is listed with its period, submission date, and status: **Pending review**, **Approved** (with the amount credited to your wallet), or **Rejected** (with the reason). ## Apply for Invoice Billing 1. On **Payment Method**, find the **Invoice Billing** section and click **Enable**. 2. In **Request postpaid billing**, optionally attach **Supporting documents** — for example business registration, PAN, GST registration, or a signed postpaid agreement (PDF only, up to 5 files, 10 MB each). 3. Click **Request postpaid**. The billing team reviews the request; Invoice Billing starts only after approval. While it is under review, click **View request** to see what you sent. If it is rejected, the section shows the date you can apply again; from then, click **Request again**. After approval, the section shows your credit usage — see [Invoice Billing](/docs/platform-fundamentals/billing-and-usage#invoice-billing). ## Billing admission checks Before creating a billable resource, the platform checks your organization's billing state and balance. If the check fails, the portal explains why and, when adding credits would resolve it, offers **Add Credits**. See [Billing admission checks](/docs/platform-fundamentals/billing-and-usage#billing-admission-checks). ## Next steps * Track spending on **Billing → Summary** and **Billing → Usage**, and download invoices from **Billing → Invoices**. See [Billing and usage](/docs/platform-fundamentals/billing-and-usage). * Review your plan's resource limits in [Limits & Quotas](/docs/platform-fundamentals/limits-and-quotas). ## Related pages * [Billing and usage](/docs/platform-fundamentals/billing-and-usage) * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Dashboard & navigation](/docs/getting-started/overview/dashboard-navigation) --- title: Dashboard & Navigation url: https://ibee.ai/docs/getting-started/overview/dashboard-navigation description: Navigate the IBEE Solutions portal — select an organization, browse workspaces, switch between them, and access resources, billing, and settings from the sidebar. last_updated: 2026-10-19 --- # Dashboard & Navigation > Navigate the IBEE Solutions portal — select an organization, browse workspaces, switch between them, and access resources, billing, and settings from the sidebar. The IBEE Solutions portal is organized around **organizations** and **workspaces**. Sign in, pick an organization, then pick a workspace to access resources. Billing, team management, and settings live at the organization level; compute, storage, and networking live inside workspaces. ## Organizations page After sign-in, the portal shows the **Organizations** page. Each organization card displays: * The **organization name** * An account-type tag (e.g. **Individual** or **Business**) * The billing **currency** (e.g. **INR**) Click a card to open the organization. To create a new one, click **Create Organization** in the top right. See [Create an organization](/docs/getting-started/account-setup/create-an-organization). The page also shows: * **Pending invitations** from other organizations, with **Accept** and **Decline** buttons. See [Accepting an invitation](/docs/platform-fundamentals/team-members-access-roles#accepting-an-invitation). * Your organization usage, for example *"1 of 3 owned organizations used. Joined 2 of 20 organizations."* See [Organization limits](/docs/platform-fundamentals/limits-and-quotas#organization-limits). If you don't belong to any organization yet, the page shows **No organizations yet** and a **Create New Organization** button. ## Workspaces page Inside an organization, the **Workspaces** page lists all workspaces and shows how many are in use (for example *"3 of 5 workspaces used"*). Every new organization starts with three workspaces: **production**, **dev**, and **stage**. Each card shows: * The **workspace name** (click the pencil icon to rename) * A **type** tag: Production, Dev, Stage, or Custom Click a workspace card to enter it. The portal opens the first resource page (Bare Metal Servers) directly. Only organization **Admins** can create or rename workspaces. Workspaces can't be deleted from the portal. ### Create a workspace Click **Create Workspace** in the top right. In the dialog, set: * **Type** (required) — Production (default), Dev, or Stage * **Name** (optional) — defaults to the type name (e.g. "production") Click **Create workspace** to confirm. The portal navigates straight to the new workspace's resource page. > **Info** > > Each organization supports up to **5 workspaces**, including the three default ones. For a higher limit, contact [support@ibee.ai](mailto:support@ibee.ai). ## The sidebar The sidebar changes depending on whether the current view is at the **organization level** or inside a **workspace**. There is no separate dashboard page — after you choose an organization, you land on its Workspaces page. ### Organization-level sidebar Visible on the Workspaces page and organization settings: * **Organization** — Workspaces, Organization Details, Team, API Tokens, Activity Logs * **Billing** — Summary, Usage, Invoices, Payment Method, Usage Limits ### Workspace-level sidebar Visible inside a workspace: * **Infrastructure** — Bare Metal Servers, GPU VMs, Cloud VMs, Object Storage, Block Storage, Container Registry * **Network & Security** — VPC, Reserved IPs, Load Balancer, DNS, CDN, Firewalls, SSL Certificates * **Tools** — Backups, Snapshots, ISOs, SSH Keys, Email Service, Secret Manager * **Workspace** — Workspace Details (returns to the Workspaces list) Organization-level pages (Team, API Tokens, Activity Logs, and billing) are not in the workspace sidebar. Use **Workspace Details** or the organization switcher to return to the organization level. Some products are enabled for organizations in stages, so your sidebar may not show every item listed here. Your access role also hides pages you can't use — for example, Billing members see only the **Billing** section. See [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles). ## Switching organizations and workspaces The top bar shows a **breadcrumb-style switcher**: `Organization ▾ / Workspace ▾`. Click either chevron to open a two-column panel: * **Left column (Organizations)** — search and select any organization. Includes **All Organizations** and **New Organization** links. * **Right column (Workspaces)** — search and select a workspace within the current organization. Includes **All Workspaces** and **New Workspace** links. Selecting an organization opens its Workspaces page. Selecting a workspace opens its resources. ## Billing at a glance To check spending, open **Billing → Summary** for this month's usage charges, or **Billing → Payment Method** for your wallet balances and to purchase credits. See [Add billing](/docs/getting-started/account-setup/add-billing). ## Top bar Every page includes a persistent top bar with: * The **organization / workspace switcher** (breadcrumb dropdown) * **Support** — opens the Support Center for the current organization. See [Contact Support](/docs/support/contact-support). * **Help** (question-mark icon) — the **Need help?** menu with **Feedback**, **Documentation**, **Changelog**, and **Status** links * **Notifications** (bell icon) * **Account menu** (avatar) in the top right — **View Profile** opens your user settings, including [account security](/docs/getting-started/account-setup/account-security); **Logout** signs you out The Support link appears only for roles that can open support requests (Admin and Technical). ## Navigation flow summary ``` Sign in → Organizations page (select an organization) → Workspaces page (select a workspace) → Resource pages (Bare Metal, GPU VMs, Cloud VMs, Storage, etc.) ``` Organization-level pages (Billing, Team, API Tokens, Activity Logs) are accessible from the organization sidebar without entering a workspace. ## Related pages * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Add billing](/docs/getting-started/account-setup/add-billing) * [Verify your identity](/docs/getting-started/account-setup/verify-your-identity) * [Regions and locations](/docs/getting-started/overview/regions-and-locations) --- title: Regions & Locations url: https://ibee.ai/docs/getting-started/overview/regions-and-locations description: Where IBEE Solutions runs — data center locations, region codes, and availability for compute, storage, and networking resources. last_updated: 2026-10-27 --- # Regions & Locations > Where IBEE Solutions runs — data center locations, region codes, and availability for compute, storage, and networking resources. IBEE Solutions resources are deployed into **regions** — isolated data center locations identified by a short region code. The API takes a site ID, not the region code: list the sites with [List compute sites](/docs/api-reference/compute-catalog/list-compute-sites) and pass the `site_id` you choose. ## Asia | Location | Region code | | ---------------- | ----------- | | Amaravati, India | VGA | | Hyderabad, India | HYD | ## Americas | Location | Region code | | ------------ | ----------- | | Ashburn, USA | IAD | ## Choosing a region Pick the region closest to your end users or workload: * **India-based users or workloads** — use `VGA` (Amaravati). Use `HYD` for active-active or DR pairing once available. * **US-based users or workloads** — use `IAD` (Ashburn, Virginia). * **Global services** — combine regions by deploying resources in more than one location. ## Related pages * [Getting started](/docs/getting-started/account-setup/sign-up) * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Deploy your first resource](/docs/infrastructure/cloud-vms/create-a-vm) * [Billing and usage](/docs/platform-fundamentals/billing-and-usage) --- title: First resource url: https://ibee.ai/docs/getting-started/overview/first-resource description: Launch your first IBEE Solutions resource — a Cloud VM — in under 5 minutes. last_updated: 2026-10-27 --- # First resource > Launch your first IBEE Solutions resource — a Cloud VM — in under 5 minutes. The fastest way to get started with IBEE Solutions is to deploy a Cloud VM. This page walks you through the minimum steps from a fresh organization to a running server. ## Before you begin 1. **Sign up** — [Create an IBEE Solutions account](/docs/getting-started/account-setup/sign-up). 2. **Verify** — Complete [account verification](/docs/getting-started/account-setup/verify-your-identity) to unlock compute access. 3. **Create an organization** — [Set up an organization](/docs/getting-started/account-setup/create-an-organization) to group your resources and billing. 4. **Add credits** — Go to **Billing → Payment Method** in the sidebar and click **Purchase credits**. The platform checks your wallet balance before deploying. See [Add billing](/docs/getting-started/account-setup/add-billing). ## Launch a Cloud VM ### Open Cloud VMs In the portal sidebar, click **Cloud VMs** under **Products**, then click **Create server**. ### Pick a region, plan, and OS 1. Select **Asia → Amaravati (AVR)** as the region. 2. Choose a plan — `perf.1.c2.m4` is a good starting point. 3. Under **Operating System → Templates**, pick **Ubuntu → Ubuntu 24.04**. ### Add an SSH key and deploy 1. Under **SSH Keys**, paste your public key (or click **+ New** to add one). 2. Enter a hostname (e.g. `my-first-vm`). 3. Click **Deploy Now**. ### Connect Once the VM shows **Running**, copy the public IP and SSH in: ```bash ssh ubuntu@ ``` ## What to explore next * **Block Storage** — [Create a volume](/docs/infrastructure/block-storage/create-a-volume) and attach persistent storage to your VM. * **Object Storage** — [Upload your first object](/docs/infrastructure/object-storage) to an S3-compatible bucket. * **Firewalls** — [Create firewall rules](/docs/network-security/firewalls/create-firewall-rules) to control inbound traffic. * **Backups** — [Enable backups](/docs/tools/backups/enable-backups) for automated recovery points. ## Related pages * [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) (detailed 5-minute quickstart) * [Dashboard](/docs/getting-started/overview/dashboard-navigation) * [Billing and usage](/docs/platform-fundamentals/billing-and-usage) --- title: Bare Metal Servers url: https://ibee.ai/docs/infrastructure/bare-metal description: Dedicated physical servers on IBEE Solutions with full hardware access — browse the Dell hardware catalog in the portal and talk to sales to order. last_updated: 2026-09-28 --- # Bare Metal Servers > Dedicated physical servers on IBEE Solutions with full hardware access — browse the Dell hardware catalog in the portal and talk to sales to order. Bare Metal Servers are dedicated physical machines — no hypervisor, no neighbors. You get full hardware access and predictable performance for databases, latency-sensitive workloads, licensing scenarios that require physical cores, and anything that shouldn't share a host. Ordering is **sales-assisted**: the portal shows the hardware catalog, and the IBEE sales team configures, prices, and provisions the server with you. There's no self-service deploy button for bare metal. ## Hardware catalog In the portal sidebar, open **Infrastructure → Bare Metal Servers**. The page lists the available Dell configurations: | Model | RAM | Storage | RAID | | --------- | --------------------- | ------------------------------ | ---------------- | | Dell R220 | Up to 32 GB DDR3 ECC | Up to 4 TB SSD/HDD | RAID 1 | | Dell R230 | Up to 64 GB DDR4 ECC | Up to 16 TB SSD/HDD | RAID 1, 5, 10 | | Dell R240 | Up to 64 GB DDR4 ECC | Up to 32 TB SSD/HDD | RAID 1, 5, 10 | | Dell R430 | Up to 384 GB DDR4 ECC | Up to 18 TB SSD / 40 TB HDD | RAID 1, 5, 10 | | Dell R630 | Up to 1.5 TB DDR4 ECC | Up to 23 TB SSD / 18 TB HDD | RAID 1, 5, 10 | | Dell R640 | Up to 3 TB DDR4 ECC | Up to 76.8 TB NVMe / 64 TB HDD | RAID 1, 5, 10 | | Dell R730 | Up to 3 TB DDR4 ECC | Up to 64 TB HDD / 29 TB SSD | RAID 1, 5, 6, 10 | To order one of these — or a configuration outside these ranges — click **talk to sales** on the Bare Metal Servers page. See [Provision a server](/docs/infrastructure/bare-metal/provision-a-server). ## Locations | Region | Location | Code | Status | | ------ | ---------------------- | ---- | ----------- | | Asia | Amaravati, India | VGA1 | Available | | Asia | Hyderabad, India | HYD2 | Available | | Europe | Amsterdam, Netherlands | AMS1 | Coming soon | ## Pricing Pricing is monthly in INR, plus 18% GST. The portal doesn't show bare metal prices — ask the sales team for a quote for your configuration, including the operating system (some, such as Windows, carry a licence fee) and network port. ## Related pages * [Provision a server](/docs/infrastructure/bare-metal/provision-a-server) * [Cloud VMs](/docs/infrastructure/cloud-vms) — instant self-service VMs * [GPU VMs](/docs/infrastructure/gpu-vms) --- title: Provision a server url: https://ibee.ai/docs/infrastructure/bare-metal/provision-a-server description: Order a bare metal server on IBEE Solutions — review the hardware catalog in the portal, then talk to sales to configure, price, and provision it. last_updated: 2026-09-28 --- # Provision a server > Order a bare metal server on IBEE Solutions — review the hardware catalog in the portal, then talk to sales to configure, price, and provision it. Bare metal provisioning is sales-assisted. The portal shows the hardware catalog; you then contact the IBEE sales team, who confirm the configuration, pricing, and provisioning with you. There's no self-service configurator or deploy button for bare metal in the portal. ## Before you begin * A verified IBEE Solutions organization with billing set up ([Add billing](/docs/getting-started/account-setup/add-billing)). * An idea of your requirements — see the checklist below. ## Request a server ### 1. Review the hardware catalog In the portal sidebar, open **Infrastructure → Bare Metal Servers**. The table lists each Dell model with its maximum **RAM**, **Storage**, and supported **RAID** levels. See [Bare Metal Servers](/docs/infrastructure/bare-metal#hardware-catalog) for the full list. ### 2. Talk to sales Click **talk to sales** in the banner above the table (**Customization available, click here to talk to sales**). The IBEE contact page opens in a new browser tab. ### 3. Send your requirements Tell the sales team what you need. Include: | Item | Examples | | -------------------- | ------------------------------------------------------------------------------------------------------- | | **Location** | Amaravati (VGA1) or Hyderabad (HYD2), India. Amsterdam (AMS1), under the Europe region, is coming soon. | | **Hardware** | A catalog model, or custom CPU, RAM, storage, and RAID requirements. | | **Operating system** | The OS and version you want installed. Some, such as Windows, carry a licence fee. | | **Network** | Port speed and bandwidth needs. | | **Hostname** | For example `my-baremetal-01`. | ### 4. Confirm and provision The sales team confirms the configuration and monthly price (INR, plus 18% GST) and arranges provisioning with you. > **Info** > > Bare metal servers are provisioned by the IBEE team rather than instantly. For instant self-service compute, use [Cloud VMs](/docs/infrastructure/cloud-vms/create-a-vm) or [GPU VMs](/docs/infrastructure/gpu-vms/create-a-gpu-vm). ## Troubleshooting **I can't find a Deploy button on the Bare Metal Servers page** That's expected — ordering goes through sales. Click **talk to sales**. **The configuration I need isn't in the catalog** The catalog shows standard ranges. Custom hardware is available on request — click **talk to sales** and describe what you need. ## Related pages * [Bare Metal overview](/docs/infrastructure/bare-metal) * [Add billing](/docs/getting-started/account-setup/add-billing) * [Cloud VMs](/docs/infrastructure/cloud-vms) --- title: GPU VMs url: https://ibee.ai/docs/infrastructure/gpu-vms description: GPU-backed virtual machines on IBEE Solutions for AI inference, training, rendering, and other accelerated workloads — deployed and managed like Cloud VMs, with per-GPU metrics. last_updated: 2026-10-26 --- # GPU VMs > GPU-backed virtual machines on IBEE Solutions for AI inference, training, rendering, and other accelerated workloads — deployed and managed like Cloud VMs, with per-GPU metrics. GPU VMs are KVM-based virtual machines with NVIDIA GPUs attached. Use them for model training and fine-tuning, inference APIs, rendering, video processing, and any workload that needs GPU acceleration. You deploy and manage them from the portal much like [Cloud VMs](/docs/infrastructure/cloud-vms), with a GPU plan catalog and an extra **GPU Metrics** tab. > **Info** > > **Ready to deploy?** Follow [Create a GPU VM](/docs/infrastructure/gpu-vms/create-a-gpu-vm). ## What you can do * Deploy GPU plans that combine a GPU model and GPU memory with vCPU, RAM, and disk — up to 5 identical VMs at once. * Boot from GPU-compatible OS templates, or from an ISO, snapshot, or backup. * Sign in with SSH keys (Linux) or a password, shown under **Overview → Connection Details**. * Connect with a public IP, or place the VM in a VPC with **Private + NAT** or **Private only** networking. Attach Reserved IPs and protect it with a firewall group. * Watch CPU, memory, disk, and network on the **Monitoring** tab, and GPU utilization, VRAM, temperature, and power on the **GPU Metrics** tab. * Protect data with scheduled [backups](/docs/tools/backups) and manual [snapshots](/docs/tools/snapshots). * Change plans and manage IPs, VPCs, SSH keys, and passwords from the **Settings** tab. ## Find GPU VMs in the portal In the portal sidebar, open **Infrastructure → GPU VMs**. The **GPU Virtual Machines** page lists your GPU VMs with their **Instance**, **OS**, **Location**, **IP Address**, and **Status**. Click **Deploy GPU VM** to create one, or click a row to open its detail page. ## How GPU VMs differ from Cloud VMs | | GPU VMs | Cloud VMs | | --------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | **Plans** | Each plan lists the GPU model and GPU memory, plus vCPU, RAM, disk, and price. | vCPU, memory, storage, and bandwidth. See [Instance types](/docs/infrastructure/cloud-vms/instance-types). | | **Billing** | **Hourly**. | **Hourly**, or **Monthly** / **Yearly** commitments where offered. | | **Templates** | Only GPU-compatible images are listed. | Only Cloud VM images are listed. | | **Detail tabs** | Overview, Monitoring, **GPU Metrics**, Backups, Snapshots, Settings. | Overview, Monitoring, Backups, Snapshots, Settings. | Everything else — location, SSH keys, network configuration, instance count, hostnames, power actions, and the delete dialog — works the same way as for Cloud VMs. ## Lifecycle of a GPU VM | Stage | What you do | Where | | ----------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | **Deploy** | Pick location, GPU plan, OS, SSH keys, network, and hostname. | [Create a GPU VM](/docs/infrastructure/gpu-vms/create-a-gpu-vm) | | **Set up** | Confirm the GPU with `nvidia-smi`; install a compatible NVIDIA driver if it's missing. | [Create a GPU VM](/docs/infrastructure/gpu-vms/create-a-gpu-vm#verify) | | **Operate** | Start, stop, reboot; watch **Monitoring** and **GPU Metrics**. | [Power actions](/docs/infrastructure/cloud-vms/power-actions) | | **Connect** | Manage public IP, Reserved IPs, VPCs, and access. | [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) | | **Protect** | Enable scheduled backups or take manual snapshots. | [Backups](/docs/tools/backups) · [Snapshots](/docs/tools/snapshots) | | **Scale** | Change plan from **Settings → Change Plan**. | [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm) | | **Retire** | Delete the VM, optionally keeping its public IP as a Reserved IP. | [Power actions](/docs/infrastructure/cloud-vms/power-actions#delete) | ## GPU Metrics The **GPU Metrics** tab charts **GPU Utilization**, **VRAM Utilization**, **Temperature**, and **Power Draw** over **30m**, **1h**, **6h**, **24h**, or **7d**. Collection is off until you turn it on: 1. Start the VM, and make sure `qemu-guest-agent` is running inside it. 2. On **GPU Metrics**, click **Enable monitoring**. A lightweight IBEE agent is installed through the guest agent — it opens no network port on the VM. 3. If the tab shows **NVIDIA guest driver required**, install a compatible NVIDIA driver inside the VM. Monitoring starts automatically once `nvidia-smi` works; CUDA is optional. If the agent goes offline or setup fails, the tab explains why and offers **Repair monitoring**. Historical values stay visible while the VM is stopped. > **Info** > > Browser console access isn't available in the portal yet — the **Console** action is shown as **Soon**. Use SSH or RDP with the details under **Overview → Connection Details**. ## Related pages * [Create a GPU VM](/docs/infrastructure/gpu-vms/create-a-gpu-vm) * [Cloud VMs](/docs/infrastructure/cloud-vms) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [SSH Keys](/docs/tools/ssh-keys) --- title: Create a GPU VM in the portal url: https://ibee.ai/docs/infrastructure/gpu-vms/create-a-gpu-vm description: Deploy a GPU-enabled virtual machine on IBEE Solutions for AI, ML, rendering, and compute-intensive workloads. last_updated: 2026-10-26 --- # Create a GPU VM in the portal > Deploy a GPU-enabled virtual machine on IBEE Solutions for AI, ML, rendering, and compute-intensive workloads. Deploy one or more GPU-enabled virtual machines (VMs) from the IBEE Solutions portal. GPU VMs include NVIDIA GPUs for AI/ML training, inference, rendering, and other GPU-accelerated workloads. The **Deploy** page is a single scrolling form with a running summary and the **Deploy** button in the bottom bar. ## Before you begin * An IBEE Solutions account with write access to the workspace. * A verified account to unlock server deployment ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)). * Sufficient wallet credits — the platform checks your balance before deploying ([Billing and usage](/docs/platform-fundamentals/billing-and-usage)). ## Deploy a GPU VM ### 1. Open GPU VMs In the portal sidebar, open **Infrastructure → GPU VMs**, then click **Deploy GPU VM**. ### 2. Select a location Under **Location**, select a region tab and choose a data center location within it. GPU availability varies by location. ### 3. Choose a GPU plan Under **Choose Plan**, select a plan. Each row lists the **GPU** model and its **Memory**, plus **vCPU**, **RAM**, **Disk**, and the price per month and per hour. GPU VMs are billed **Hourly**. ### 4. Select the operating system Pick a source for the boot disk under **Operating System**: | Tab | Use it for | | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Templates** | OS images maintained by IBEE. The default. Only GPU-compatible images are listed. | | **ISOs** | Boot from an ISO you added under **Tools → ISOs**. Interactive installs need a console, which isn't available in the portal yet. | | **Snapshots** | Create the VM from a snapshot captured from another VM. | | **Backups** | Create the VM from a scheduled backup recovery point. | On **Templates**, pick an OS family card, then choose a version from the **OS Version** dropdown. For a Windows image, the Windows licence is added automatically and its monthly price per VM appears in the bottom bar. ### 5. Add SSH keys (Linux) For Linux images, the **SSH Keys** section appears (it's hidden for Windows images). Open **Select SSH Keys** and pick one or more saved keys, or click **Add Key** to create a key pair or import a public key. A Linux VM deployed without a key uses password login, shown under **Overview → Connection Details**. See [SSH Keys](/docs/tools/ssh-keys). ### 6. Configure the network Under **Network Configuration**, choose **Internet and VPC access**: * **Public IP** *(default)* — direct inbound and outbound IPv4. Optionally pick a VPC and subnet. Under **Reserved public IP**, keep **Allocate automatically** or pick one of your unattached Reserved IPs, with or without a VPC. * **Private + NAT** — primary interface in a NAT Gateway VPC with outbound internet only. * **Private only** — primary interface in a VPC with no internet route. Under **Firewall**, pick a firewall group or click **Create Group**. If you don't pick one, the default firewall group is attached automatically. See [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) for details — the options are the same as for Cloud VMs. ### 7. Set VM details Under **VM Details**: * **Instances** — deploy up to **5** VMs at once. The maximum can be lower when GPU capacity or public addresses in the location are limited, and it's **1** when you pick a specific Reserved IP. * **Hostname** — use lowercase letters, numbers, and hyphens. With more than one instance, this becomes the base hostname and each instance is prefilled as `-1`, `-2`, and so on; edit them under **Instance hostnames**. Every hostname must be unique. ### 8. Deploy Review the summary in the bottom bar, then click **Deploy** (or **Deploy N VMs**). The platform first checks your organization's billing state and wallet balance. If the check passes, provisioning starts and you return to the GPU VMs list. If not, a **Billing needs attention** popup appears — click **Add Credits** to top up and return. ## Verify Once provisioned, your GPU VM appears in the **GPU Virtual Machines** list with status **Running**. Click it to open the detail page. **Overview → Connection Details** shows the SSH command (or username and password, or RDP details for Windows). Confirm GPU access inside the VM: ```bash nvidia-smi ``` If `nvidia-smi` isn't found, install a compatible NVIDIA driver for your OS inside the VM. ## Use the API The API operation is `POST /compute/gpu-vms`. It takes the same network fields as a cloud VM create (`vpc_id`, `subnet_id`, `network_connectivity`, `vpc_attachment_mode`, `reserved_public_ip_id`) and inline public keys in `ssh_keys`, plus `gpu_model` and `gpu_count`. The API accepts Linux images only (`os_type: linux`). Most other GPU VM operations mirror the cloud VM ones under `/compute/gpu-vms/{vm_id}`. The **GPU Metrics** tab has no public API operation yet. ## Manage your GPU VM From the VM detail page, use **Actions** to control your server: | Action | Description | | ------- | ---------------------------------------------------------------------------------------------------------------------- | | Start | Power on a stopped server | | Stop | Shut down a running server | | Reboot | Restart the server | | Console | Shown as **Soon** — browser console access isn't available in the portal yet | | Delete | Permanently delete the server — you type the VM name to confirm, and can choose to keep its public IP as a Reserved IP | The detail page has these tabs: | Tab | What it's for | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Overview** | Specs, network, and **Connection Details**. | | **Monitoring** | CPU, memory, storage, disk, and network charts, plus recent activity. See [Monitoring](/docs/infrastructure/cloud-vms/monitoring). | | **GPU Metrics** | GPU utilization, VRAM, temperature, and power. Click **Enable monitoring** first — see [GPU Metrics](/docs/infrastructure/gpu-vms#gpu-metrics). | | **Backups** / **Snapshots** | Recovery points. See [Backups](/docs/tools/backups) and [Snapshots](/docs/tools/snapshots). | | **Settings** | **Change Plan**, **IPv4 & Reserved IP**, **VPC Networks**, and **Access** (SSH keys, password login, password reset). **Change OS** and **Hostname** aren't available yet. See [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm) and [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms). | > **Warning** > > Deleting a GPU VM is permanent and cannot be undone. Back up your data and snapshots before deleting. ## Troubleshooting **Deploy shows an error message** The portal validates the form when you click **Deploy** and names the missing item — for example a plan, an OS version, a subnet, or a unique hostname for each instance. **Billing needs attention popup** Your organization's billing state or wallet balance blocks the deploy. Click **Add Credits** to top up, then return. **`nvidia-smi` not found** The NVIDIA driver isn't installed on the selected image. Install a compatible NVIDIA driver inside the VM. The **GPU Metrics** tab also shows **NVIDIA guest driver required** until it's installed. **Server stuck in provisioning** Wait a few minutes. If the status does not update, contact [IBEE support](/docs/support/contact-support). ## Related pages * [GPU VMs overview](/docs/infrastructure/gpu-vms) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [Power actions](/docs/infrastructure/cloud-vms/power-actions) * [SSH Keys](/docs/tools/ssh-keys) --- title: Cloud VMs url: https://ibee.ai/docs/infrastructure/cloud-vms description: Launch and manage virtual machines on IBEE Solutions — flexible compute for web apps, APIs, backends, databases, and dev environments. last_updated: 2026-10-26 --- # Cloud VMs > Launch and manage virtual machines on IBEE Solutions — flexible compute for web apps, APIs, backends, databases, and dev environments. IBEE Solutions VMs are KVM-based virtual machines you can deploy in minutes from the IBEE Solutions portal, the [`ibee`](/docs/infrastructure/cloud-vms/launch-your-first-vm#using-the-ibee-cli) CLI, or the API. Pick a location, plan, operating system, and network — your server is provisioned with a root disk, a bandwidth allowance, and either a public IP or a private VPC interface. > **Info** > > **New here?** Follow the 5-minute [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) quickstart. ## What you can do * Deploy general-purpose servers (Linux or Windows) in supported regions — up to 5 identical VMs at once. * Pay **Hourly**, or commit **Monthly** or **Yearly** where the plan offers it. * Connect with a public IP, or put the VM in a VPC with **Private + NAT** or **Private only** networking. Attach [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips) and protect it with a firewall group. * Change plans without rebuilding — upgrade CPU, RAM, and disk, or downgrade CPU and RAM. * Manage SSH keys, password login, and password resets from **Settings → Access**. * Attach block storage volumes for persistent data outside the root disk. * Take **snapshots** as on-demand recovery points, or schedule **automated backups**. * Restore in place, restore a single disk, or create a new VM from any recovery point. * Monitor CPU, memory, storage, disk I/O, and network throughput in the portal. * Automate the public VM create, read, power, metrics, and delete operations via the [`ibee` CLI](/docs/infrastructure/cloud-vms/launch-your-first-vm#using-the-ibee-cli) and the IBEE Solutions API. ## Find your VMs In the portal sidebar, open **Infrastructure → Cloud VMs**. The **Cloud Virtual Machines** list shows each VM's **Instance**, **OS**, **Location**, **IP Address**, and **Status**. Use **Search or filter VMs...** to find a VM, the sort menu to order by **Created**, **Name**, **Status**, or **OS** (choose **Use Ascending** to reverse the order), and the page controls to move through long lists. Click a row to open the VM. From the API, `GET /compute/cloud-vms` lists VMs a page at a time (`limit` default 10, up to 100, plus `offset`). ## Instance families Two families are available — choose by workload profile, then pick a size within the family. | Family | Use case | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | [Standard VMs](/docs/infrastructure/cloud-vms/instance-types) | Balanced vCPU and memory for everyday production workloads — web apps, SaaS, APIs, small to medium databases. | | [Performance VMs](/docs/infrastructure/cloud-vms/instance-types) | Compute-optimized with higher CPU density — high-traffic web servers, gaming, batch processing, distributed systems. | For accelerated workloads (training, inference, rendering), see [GPU VMs](/docs/infrastructure/gpu-vms). ## Regions and locations Cloud VMs are available in the **Asia** region, in data centers in Amaravati and Hyderabad, India. The Deploy page lists the locations open to your organization. See [Regions and locations](/docs/getting-started/overview/regions-and-locations) for the full availability matrix. > **Info** > > Browser console access to VMs isn't available in the portal yet. Use SSH or RDP with the details under **Overview → Connection Details**, and **Settings → Access** to recover SSH access. ## Lifecycle of a VM | Stage | What you do | Where | | ------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Deploy** | Pick location, plan, OS, SSH keys, network, billing term, and hostname. | [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) | | **Configure** | Attach volumes, adjust firewall rules, attach VPCs and Reserved IPs. | [Attach volumes](/docs/infrastructure/cloud-vms/attach-volumes) · [Networking](/docs/infrastructure/cloud-vms/networking-for-vms) | | **Operate** | Monitor metrics, run power actions, manage access. | [Monitoring](/docs/infrastructure/cloud-vms/monitoring) · [Power actions](/docs/infrastructure/cloud-vms/power-actions) | | **Protect** | Enable scheduled backups or take manual snapshots. | [Backups](/docs/tools/backups) · [Snapshots](/docs/tools/snapshots) | | **Scale** | Change plan to upgrade CPU, RAM, or disk, or downgrade CPU and RAM — no rebuild required. | [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm) | | **Retire** | Stop and delete when no longer needed. | [Power actions](/docs/infrastructure/cloud-vms/power-actions#delete) | ## Related pages * [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Instance types](/docs/infrastructure/cloud-vms/instance-types) * [Monitoring](/docs/infrastructure/cloud-vms/monitoring) * [Backups](/docs/tools/backups) * [Snapshots](/docs/tools/snapshots) --- title: Create a VM url: https://ibee.ai/docs/infrastructure/cloud-vms/create-a-vm description: Deploy one or more Cloud VMs on IBEE Solutions — choose a location, plan, operating system, SSH keys, network, billing term, and hostname, then click Deploy. last_updated: 2026-10-26 --- # Create a VM > Deploy one or more Cloud VMs on IBEE Solutions — choose a location, plan, operating system, SSH keys, network, billing term, and hostname, then click Deploy. Deploy one or more cloud virtual machines (VMs) from the IBEE Solutions portal. The **Deploy** page is a single scrolling form — location, plan, operating system, access, network, billing, and VM details — with a running cost summary and the **Deploy** button in the bottom bar. ## Before you begin * An IBEE Solutions account with write access to the workspace. * A verified account to unlock server deployment ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)). * Sufficient wallet credits — the platform checks your balance before deploying ([Billing and usage](/docs/platform-fundamentals/billing-and-usage)). * Optional, depending on how you want to connect the VM: * An [SSH key](/docs/tools/ssh-keys) (you can also create one during deploy). * A [VPC](/docs/network-security/vpc-ip-management) with at least one subnet in the target location. * A [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) in the target location. * A [firewall group](/docs/network-security/firewalls) (you can also create one during deploy). ## Deploy a Cloud VM ### 1. Open the Deploy page In the portal sidebar, open **Infrastructure → Cloud VMs**, then click **Deploy VM**. ### 2. Select a location Under **Location**, pick a region tab (for example **Asia**), then choose a data center location. Plans, images, VPCs, and Reserved IPs further down the page are filtered to this location. See [Regions and locations](/docs/getting-started/overview/regions-and-locations) for availability. ### 3. Choose a plan Under **Choose Plan**, filter by **All**, **Standard**, or **Performance**, then select a plan. Each row shows the plan's vCPU, memory, storage, included bandwidth, and price per month and per hour. The portal checks that the plan can be placed in the selected location before you deploy. See [Instance types](/docs/infrastructure/cloud-vms/instance-types) for how the plan families differ. ### 4. Select the operating system Pick a source for the boot disk under **Operating System**: | Tab | Use it for | | ------------- | ------------------------------------------------------- | | **Templates** | Curated OS images maintained by IBEE. The default. | | **ISOs** | Boot from an ISO you added under **Tools → ISOs**. | | **Snapshots** | Create the VM from a snapshot captured from another VM. | | **Backups** | Create the VM from a scheduled backup recovery point. | On **Templates**, pick an OS family card (for example **Ubuntu** or **Windows**), then choose a version from the **OS Version** dropdown. A **Selected: \** chip confirms your choice. Only images compatible with Cloud VMs are listed. > **Info** > > Deploying from the **Backups** tab uses the captured root disk only. To restore the root disk **and** attached data disks, open the source VM's **Backups** tab and choose **Create New VM** instead. See [Restore from backup](/docs/tools/backups/restore-from-backup). > **Warning** > > An ISO install needs an interactive console, and browser console access isn't available in the portal yet. See [Custom images](/docs/infrastructure/cloud-vms/custom-images#isos) before choosing the **ISOs** tab. ### 5. Review licences and control panels If the selected plan and image have add-ons, a **Licences & control panels** section lists them with a monthly price: * For Windows images, the Windows licence is selected automatically and marked **Required for the selected Windows image**. * Other add-ons are **Optional** — click a card to add or remove it. ### 6. Add SSH keys (Linux) For Linux images, the **SSH Keys** section appears. Open **Select SSH Keys** and pick one or more saved keys. To add a new one, click **Add Key**, then either use **Create Key Pair** (the private key downloads once — keep it safe) or **Import Key** to paste or upload an existing public key. The section is hidden for Windows images, which use a password instead. > **Info** > > A Linux VM deployed without an SSH key uses password login. Its username and password appear under **Overview → Connection Details** once the VM is running. Adding a key is recommended. ### 7. Configure the network Under **Network Configuration → VM network**, choose **Internet and VPC access**: | Option | What you get | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Public IP** *(default)* | A dedicated inbound and outbound IPv4 address. The VPC is optional: keep **No VPC · public interface only** to use the platform network, or pick a VPC to make it the VM's primary interface — the public IP then maps to the VM's VPC private IP. | | **Private + NAT** | The VM's primary interface is in a NAT Gateway VPC with managed outbound internet. Inbound internet is blocked. | | **Private only** | The VM's primary interface is in a VPC with no internet route. | When you pick a VPC, also pick a **Subnet**. With **Public IP**, a **Reserved public IP** field appears, with or without a VPC: * Leave it on **Allocate automatically**, or select one of your unattached Reserved IPs in this location. * A **private** VPC requires a Reserved IP for public exposure — create one in this location before deploying. * Selecting a specific Reserved IP limits the deployment to one VM. Under **Firewall**, pick a firewall group, or click **Create Group** to create one and select it. If you don't select a group, the default firewall group is attached automatically. Manage rules from the [Firewalls](/docs/network-security/firewalls) page. See [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) for how each option behaves after deploy. ### 8. Choose a billing term Under **Billing**, choose how the VM is billed. The options offered depend on the plan: | Term | How it works | | ---------------------- | ----------------------------------------------------- | | **Hourly** *(default)* | No commitment. Usage is metered in 15-minute windows. | | **Monthly** | A fixed rate for the commitment term. | | **Yearly** | An annual commitment at the catalog rate. | Commitment cards show the equivalent hourly rate and any saving compared with Hourly. ### 9. Set VM details Under **VM Details**: * **Instances** — use **−** and **+** to deploy up to **5** VMs with the same configuration. The maximum can be lower when capacity (or, for **Public IP**, free public addresses) in the location is limited, and it is **1** when you select a specific Reserved IP. * **Hostname** — use lowercase letters, numbers, and hyphens (spaces become hyphens; other characters are removed). With more than one instance, this field becomes the **Base hostname** and each instance is prefilled as `-1`, `-2`, and so on. Edit any of them under **Instance hostnames**. Every hostname must be unique. ### 10. Deploy Check the summary in the bottom bar — it shows the estimated cost for all instances, including any licence. Then click **Deploy** (or **Deploy N VMs** for more than one instance). The platform first checks your organization's billing state and wallet balance. If the check passes, you return to the **Cloud Virtual Machines** list while the VM provisions. If not, a **Billing needs attention** popup appears — click **Add Credits** to top up, then return and deploy again. ## Verify Once provisioned, the VM appears in the **Cloud Virtual Machines** list with status **Running** and its IP address. Click it to open the detail page. **Overview → Connection Details** shows how to connect: | VM | What's shown | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Linux with an SSH key | **SSH Key Connection** — username, host, the `chmod` command for your private key, and a ready-to-copy SSH command. | | Linux without an SSH key | **SSH Connection** — username, host, and password. | | Windows | **Remote Desktop (RDP)** — IP address, username, and password. | | Private + NAT or Private only | Private SSH or RDP commands to use from inside the VPC (for example through a VPN or bastion host). | Passwords are shown only to members with write access while the VM is running. ## Launch with the ibee CLI Prefer the terminal? Use the [`ibee`](/docs/infrastructure/cloud-vms/launch-your-first-vm#using-the-ibee-cli) CLI to script VM creation. ```bash # Authenticate and select a workspace export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx" export IBEE_WORKSPACE_ID="WORKSPACE_ID" # Launch a VM ibee vms create web-01 \ --site-id SITE_ID \ --plan-id PLAN_ID \ --template-id IMAGE_ID \ --ssh-key-file ~/.ssh/id_ed25519.pub \ --wait ``` The `--wait` flag polls the asynchronous create operation until it finishes. Drop it to receive the operation immediately and poll it later with `ibee ops get --wait`. The API operation is `POST /compute/cloud-vms`. Besides the plan, image, and `billing_catalog`, it accepts the deploy-page network choices — `vpc_id` with `subnet_id`, `network_connectivity` (`public_ip`, `nat`, or `private`), `vpc_attachment_mode`, and `reserved_public_ip_id` — and inline public keys in `ssh_keys`. Attach a firewall group after create with `POST /networking/firewall-groups/{firewall_group_id}/attachments`. ### Common flags | Argument or flag | Purpose | | -------------------------------- | ------------------------------------------------------------------------------- | | `NAME` | VM display name (required positional argument). | | `--site-id` | Site ID returned by `ibee compute sites` (required by the API). | | `--plan-id` | Plan ID returned by `ibee compute plans` (required). | | `--template-id` | Image ID returned by `ibee compute images` (required). | | `--os-distro`, `--os-type` | OS distribution and family; default to the image's. | | `--cpu`, `--ram-mb`, `--disk-gb` | Compute size; default to the plan's. | | `--billing-term` | `HOURLY` or `MONTHLY`; defaults to `HOURLY` when the plan offers it. | | `--ssh-key`, `--ssh-key-file` | Public SSH key to install, inline or from a file; repeat for multiple keys. | | `--ssh-key-id` | Saved SSH key ID. Saved keys resolve for portal users only; prefer `--ssh-key`. | | `--tag` | Resource tag; repeat for multiple tags. | | `--wait` | Poll the asynchronous create operation until completion. | ### Discover available sites, plans, and images ```bash ibee compute sites ibee compute plans --vm-type cloud --site-id SITE_ID ibee compute images --vm-type cloud --site-id SITE_ID ``` For the full quickstart and CLI reference, see [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm). ## Manage your VM From the VM detail page, use **Actions** to control your server: | Action | Description | | ------ | ---------------------------------------------------------------------------------------------------------------------- | | Start | Power on a stopped server | | Stop | Shut down a running server | | Reboot | Restart the server | | Delete | Permanently delete the server — you type the VM name to confirm, and can choose to keep its public IP as a Reserved IP | The detail page also has **Overview**, **Monitoring**, **Backups**, **Snapshots**, and **Settings** tabs. Under **Settings** you can change the plan, manage the public IP and Reserved IPs, attach VPCs, and manage SSH keys and passwords. See [Power actions](/docs/infrastructure/cloud-vms/power-actions), [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm), and [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms). > **Warning** > > Deleting a VM is permanent and cannot be undone. Back up your data before > deleting. ## Troubleshooting **Deploy shows an error message** The portal validates the form when you click **Deploy** and names the missing item — for example **Please select a VM plan**, **Please select an Operating System version**, **Select a subnet for this VPC**, or **Each instance needs a unique hostname**. Fix the named field and deploy again. The button is disabled only while locations, plans, or plan availability are still loading. **Billing needs attention popup appears** Your organization's billing state or wallet balance blocks the deploy. Click **Add Credits** to top up, then return to deploy. **Only 1 VM of this plan can be deployed right now** Capacity (or free public addresses, for **Public IP**) in the location is limited. Deploy fewer instances, pick another plan or location, or use **Private + NAT**, which doesn't need a public address. **Server stuck in provisioning** Wait a few minutes. If the status does not update, contact [IBEE support](/docs/support/contact-support). ## Related pages * [SSH Keys](/docs/tools/ssh-keys) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [Take a snapshot](/docs/tools/snapshots/create-a-snapshot) * [Attach block storage](/docs/infrastructure/block-storage/attach-and-detach-a-volume) * [Power actions and delete](/docs/infrastructure/cloud-vms/power-actions) --- title: Launch your first VM url: https://ibee.ai/docs/infrastructure/cloud-vms/launch-your-first-vm description: A 5-minute quickstart for deploying your first IBEE Solutions VM from the portal or the ibee CLI. last_updated: 2026-10-19 --- # Launch your first VM > A 5-minute quickstart for deploying your first IBEE Solutions VM from the portal or the ibee CLI. This quickstart walks you through launching your first IBEE Solutions VM — pick a region, plan, and OS, deploy the server, and SSH in. You can use the portal, the [`ibee`](#using-the-ibee-cli) CLI, or the API. By the end you'll have a running Ubuntu 24.04 VM in Amaravati on a small Performance plan, accessible over SSH and ready to run your workload. ## Before you begin You'll need: * An [IBEE Solutions account](/docs/getting-started/account-setup/sign-up) — verified for compute access. * An organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)). * Sufficient wallet credits ([Billing and usage](/docs/platform-fundamentals/billing-and-usage)). * A local SSH key pair. Generate one if you don't have it: ```bash ssh-keygen -t ed25519 -C "your-email@example.com" ``` Your public key is at `~/.ssh/id_ed25519.pub`. ## Option A — Launch from the portal ### 1. Open Cloud VMs In the portal sidebar, open **Infrastructure → Cloud VMs**, then click **Deploy VM**. ### 2. Pick a region and location Under **Location**, select the **Asia** tab and **Amaravati** for this quickstart. See [Regions and locations](/docs/getting-started/overview/regions-and-locations) for the full list. ### 3. Choose a plan Pick any plan that fits your workload. For a first VM we recommend `perf.1.c2.m4` or `std.1.c4.m16` — both have enough headroom for typical web/API work. The estimated monthly and hourly cost updates as you select. **Standard VMs** — balanced vCPU, memory, included disk and bandwidth. Good default for production: | Plan | vCPU | RAM | Disk | Bandwidth | Best for | | -------------------------- | ---- | ------- | ------ | --------- | --------------------------------------------------- | | `std.1.c2.m8` | 2 | 8 GiB | 50 GB | 2 TB | Development environments, small apps, APIs, staging | | `std.1.c4.m16` *(popular)* | 4 | 16 GiB | 100 GB | 4 TB | Production web apps, SaaS, APIs, small databases | | `std.1.c8.m32` | 8 | 32 GiB | 150 GB | 6 TB | SaaS, CRM/ERP, medium databases | | `std.1.c16.m64` | 16 | 64 GiB | 200 GB | 8 TB | High-traffic apps, growing databases | | `std.1.c32.m128` | 32 | 128 GiB | 300 GB | 12 TB | Enterprise, analytics, large backends | | `std.1.c64.m256` | 64 | 256 GiB | 400 GB | 16 TB | Large-scale systems, in-memory databases | **Performance VMs** — compute-optimized with stronger CPU density per core: | Plan | vCPU | RAM | Disk | Bandwidth | Best for | | -------------------------- | ---- | ------- | ------ | --------- | -------------------------------------------------- | | `perf.1.c1.m2` | 1 | 2 GiB | 40 GB | 1 TB | Dev, testing, lightweight workloads | | `perf.1.c2.m4` | 2 | 4 GiB | 50 GB | 2 TB | First VM, microservices, API gateways | | `perf.1.c4.m8` *(popular)* | 4 | 8 GiB | 80 GB | 3 TB | High-traffic web servers, stateless apps | | `perf.1.c8.m16` | 8 | 16 GiB | 120 GB | 5 TB | Gaming servers, batch processing, CPU ML inference | | `perf.1.c16.m32` | 16 | 32 GiB | 160 GB | 8 TB | Data pipelines, container workloads | | `perf.1.c32.m64` | 32 | 64 GiB | 240 GB | 12 TB | HPC, distributed systems, compute-intensive apps | | `perf.1.c64.m128` | 64 | 128 GiB | 320 GB | 16 TB | Large compute clusters, simulations | For full network bandwidth tiers per plan and the naming convention, see [Instance types](/docs/infrastructure/cloud-vms/instance-types). ### 4. Select an operating system On the **Operating System → Templates** tab, pick **Ubuntu**, then choose **Ubuntu 24.04** from the OS Version dropdown. The available templates are filtered to show only images compatible with Cloud VMs. For ISOs, snapshots, or backups as the source, see [Custom images](/docs/infrastructure/cloud-vms/custom-images). ### 5. Add an SSH key Under **SSH Keys**, click **Add Key**, open the **Import Key** tab, give the key a name, and paste the contents of `~/.ssh/id_ed25519.pub`. If you've already saved the key, pick it from **Select SSH Keys** instead. The key is injected into the VM at first boot. See [SSH Keys](/docs/tools/ssh-keys) for full details. ### 6. Keep the default network and billing Leave **Network Configuration** on **Public IP** with **No VPC · public interface only**, and don't select a firewall group — the default firewall group is attached automatically. Leave **Billing** on **Hourly**. See [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) for the other options. ### 7. Set a hostname and deploy Under **VM Details**, keep **Instances** at 1 and enter a lowercase hostname (letters, numbers, hyphens only — for example `web-01`). Then click **Deploy** in the bottom bar. The platform checks your billing state and wallet balance first. If credits are sufficient, you return to the Cloud VMs list while the VM provisions. If not, a **Billing needs attention** popup prompts you to add credits. ### 8. Connect Once the status shows **Running**, open the VM and copy the SSH command from **Overview → Connection Details**, or copy the public IP from the Cloud VMs list and SSH in: ```bash ssh ubuntu@ ``` If SSH times out, check that the VM's firewall group allows port 22 from your address. You're done — you have a running VM. Next steps below. ## Option B — Using the ibee CLI `ibee` is the official IBEE Solutions command-line tool. Use it to launch and manage VMs from scripts, CI/CD, and your terminal. ### Install Install Python 3.10 or later, then install the CLI from PyPI: ```bash python3 -m pip install --upgrade ibee-cli ``` On Windows, use `py -m pip install --upgrade ibee-cli`. Verify the install by running `ibee --version`. ### Authenticate Generate an API token in the portal under **Organization → API Tokens**, then export the token and workspace used by your commands: ```bash export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx" export IBEE_WORKSPACE_ID="WORKSPACE_ID" ``` ### Launch a VM A VM create request uses IDs returned by the compute catalog. List valid sites, plans, and images first: ```bash ibee compute sites ibee compute plans --vm-type cloud --site-id SITE_ID ibee compute images --vm-type cloud --site-id SITE_ID ``` Pass the returned IDs to `vms create`. The name is the first positional argument. `--ssh-key-file` installs your local public key on the VM. Omit `--site-id` to let IBEE select a site automatically: ```bash ibee vms create web-01 \ --site-id SITE_ID \ --plan-id PLAN_ID \ --template-id IMAGE_ID \ --ssh-key-file ~/.ssh/id_ed25519.pub \ --wait ``` Create and power actions are asynchronous. `--wait` polls the returned operation until it finishes; without it, save the operation ID and check it later with `ibee ops get --wait`. ### Helpful CLI commands | Command | Description | | -------------------------------------- | ------------------------------------------ | | `ibee vms list` | List Cloud VMs in the current workspace | | `ibee vms get ` | Show one VM's details | | `ibee vms metrics ` | Show current resource-usage metrics | | `ibee vms stop --wait` | Stop a running VM and wait for completion | | `ibee vms start --wait` | Start a stopped VM and wait for completion | | `ibee vms reboot --wait` | Reboot a VM and wait for completion | | `ibee vms delete --yes --wait` | Permanently delete a VM | | `ibee ops get --wait` | Poll an asynchronous operation | For full help on any command: ```bash ibee vms create --help ``` ### List available sites, plans, and images ```bash ibee compute sites ibee compute plans --vm-type cloud ibee compute images --vm-type cloud ``` ### Output as JSON Put the global `--json` option before the command for machine-readable output: ```bash ibee --json vms list | jq ``` ## Verify Whichever path you took, confirm the VM is healthy: ```bash # From your laptop ssh ubuntu@ 'uname -a; uptime' # Inside the VM sudo apt update sudo apt install -y nginx curl -I http://localhost ``` Open `http://` in a browser to see the default nginx page. ## What to do next * **Protect your data** — turn on [scheduled backups](/docs/tools/backups/enable-backups) or take a [manual snapshot](/docs/tools/snapshots/create-a-snapshot). * **Open the right ports** — add rules to the VM's [firewall group](/docs/network-security/firewalls) before exposing services beyond SSH. * **Add a domain** — point an `A` record at the VM's IP with your DNS provider. * **Add persistent storage** — [attach a Block Storage volume](/docs/infrastructure/cloud-vms/attach-volumes) for data that should outlive the VM. * **Resize when ready** — move to a larger plan from **Settings → Change Plan** ([Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm)). ## Troubleshooting **Deploy shows an error message** The portal validates the form when you click **Deploy** and names the missing item — for example a plan, an OS version, or a hostname. Fix it and click **Deploy** again. **Billing needs attention popup** Your organization's wallet balance is insufficient for the selected plan. Click **Add Credits** to top up, then return to deploy. **SSH connection refused** Wait until the VM shows **Running** and the public IP is populated. The first `sshd` start takes a few seconds after the IP is assigned. **`ibee: command not found`** Re-open your shell after installation, or add the Python user scripts directory to `PATH`. **The CLI reports a missing token or workspace** Set `IBEE_TOKEN` and `IBEE_WORKSPACE_ID`, or pass the global `--token` and `--workspace` options before the command group. Generate tokens under **Organization → API Tokens**. ## Related pages * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Instance types](/docs/infrastructure/cloud-vms/instance-types) * [SSH Keys](/docs/tools/ssh-keys) * [API Tokens](/docs/tools/api-tokens) * [Power actions](/docs/infrastructure/cloud-vms/power-actions) --- title: Instance types url: https://ibee.ai/docs/infrastructure/cloud-vms/instance-types description: Choose the right Cloud VM instance type based on CPU, memory, disk, and workload profile. last_updated: 2026-10-26 --- # Instance types > Choose the right Cloud VM instance type based on CPU, memory, disk, and workload profile. IBEE Solutions VM instance types come in two families: **Standard** for balanced everyday workloads and **Performance** for compute-optimized workloads that need higher CPU density. Every instance type ships with included disk and bandwidth. ## Standard VMs — Network Bandwidth Reliable virtual machines with balanced vCPU and memory — the right default for most production workloads. Each plan ships with a private-network ceiling that scales with size and a default 100 Mbps public-network NIC. | Plan | Private Network | Public Network | Upgradable Public | | ---------------- | --------------- | ------------------ | ------------------- | | `std.1.c2.m8` | Up to 5 Gbps | 100 Mbps (default) | On request to sales | | `std.1.c4.m16` | Up to 10 Gbps | 100 Mbps (default) | On request to sales | | `std.1.c8.m32` | Up to 20 Gbps | 100 Mbps (default) | On request to sales | | `std.1.c16.m64` | Up to 25 Gbps | 100 Mbps (default) | On request to sales | | `std.1.c32.m128` | Up to 40 Gbps | 100 Mbps (default) | On request to sales | | `std.1.c64.m256` | Up to 40 Gbps | 100 Mbps (default) | On request to sales | `std.1.c4.m16` is the most popular choice for new production deployments. ## Performance VMs — Network Bandwidth Compute-optimized virtual machines with stronger CPU density, for workloads that need faster processing per core. Each plan ships with a private-network ceiling proportional to size and a default 100 Mbps public-network NIC. | Plan | Private Network | Public Network | Upgradable Public | | ----------------- | --------------- | ------------------ | ------------------- | | `perf.1.c1.m2` | Up to 2 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c2.m4` | Up to 5 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c4.m8` | Up to 10 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c8.m16` | Up to 20 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c16.m32` | Up to 25 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c32.m64` | Up to 40 Gbps | 100 Mbps (default) | On request to sales | | `perf.1.c64.m128` | Up to 40 Gbps | 100 Mbps (default) | On request to sales | `perf.1.c4.m8` is the most popular Performance plan. ### Reading the columns | Column | Meaning | | --------------------- | ------------------------------------------------------------------------------------------ | | **Private Network** | Maximum bandwidth between VMs in the same region over the IBEE backplane. | | **Public Network** | Default outbound bandwidth on the public NIC. Inbound is unmetered. | | **Upgradable Public** | The public NIC can be raised above 100 Mbps — contact IBEE sales to request a higher tier. | vCPU, RAM, and disk for each plan are encoded in the plan name (see [Naming convention](#naming-convention)). ## Choosing a family | Pick Standard if… | Pick Performance if… | | ------------------------------------------------------ | -------------------------------------------- | | Workload is memory-balanced (typical web/API/database) | Workload is CPU-bound and scales with cores | | You want the broadest fit for production | You need higher per-core throughput | | You expect mixed CPU and RAM usage | RAM is comfortable but CPU is the bottleneck | For GPU-accelerated workloads (training, inference, rendering), see [GPU VMs](/docs/infrastructure/gpu-vms). ## Naming convention Plan names follow `..c.m`: * `std.1.c4.m16` — Standard family, generation 1, 4 vCPU, 16 GiB RAM. * `perf.1.c8.m16` — Performance family, generation 1, 8 vCPU, 16 GiB RAM. The generation number changes when the underlying hardware platform is refreshed. ## What's included Every plan includes: * **NVMe root disk** sized per plan * **Outbound bandwidth** allowance per plan; inbound is unmetered * **Public IPv4 address** when deployed with **Public IP** networking ([Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms)) * **Snapshot and backup eligibility** ([Backups](/docs/tools/backups), [Snapshots](/docs/tools/snapshots)) * **Hourly billing**, plus **Monthly** or **Yearly** commitment terms where the plan offers them Storage beyond the included disk is added separately as [Block Storage](/docs/infrastructure/block-storage). Prices for each plan are shown on the Deploy page. ## Resizing between plans You can move a VM to a different plan from **Settings → Change Plan**. The VM is briefly stopped, resources are changed, and it restarts on the new plan. Upgrades grow CPU, RAM, and disk; downgrades can reduce CPU and RAM, but the disk never shrinks. See [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm). ## Related pages * [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm) * [GPU VMs](/docs/infrastructure/gpu-vms) * [Regions and locations](/docs/getting-started/overview/regions-and-locations) --- title: OS images url: https://ibee.ai/docs/infrastructure/cloud-vms/os-images description: Pick an operating system template for your Cloud VM, or boot from an ISO, snapshot, or backup — and find the credentials to sign in. last_updated: 2026-10-26 --- # OS images > Pick an operating system template for your Cloud VM, or boot from an ISO, snapshot, or backup — and find the credentials to sign in. When you deploy a Cloud VM, the **Operating System** picker lets you choose where the boot disk comes from. There are four sources. ## Sources | Tab | Use it for | | ------------- | ------------------------------------------------------------------------------------ | | **Templates** | Curated, official OS images maintained by IBEE. The fastest path to a clean install. | | **ISOs** | Boot from an ISO image you added under **Tools → ISOs**. | | **Snapshots** | Create the VM from a snapshot captured from another VM. | | **Backups** | Create the VM from a scheduled backup recovery point. | The default is **Templates**. The available images are automatically filtered based on the VM type — Cloud VM templates only appear on the Cloud VM deploy page, and GPU VM templates on the GPU VM deploy page. ## Available templates Templates are grouped by OS family — for example Ubuntu, Debian, AlmaLinux, Rocky Linux, Fedora, and Windows. The families and versions you see depend on the location and VM type. Pick the family card, then choose a version from the **OS Version** dropdown — for example `Ubuntu 24.04`. The selection is confirmed with a **Selected: \** chip below the dropdown. Windows images require a Windows licence. It's added automatically under **Licences & control panels** on the Deploy page, with its monthly price. ## How templates are built IBEE templates are derived from upstream cloud images and hardened with: * `cloud-init` for first-boot configuration (hostname, SSH keys, networking). * `qemu-guest-agent` pre-installed for [Storage Utilization metrics](/docs/infrastructure/cloud-vms/monitoring#storage-and-disk-metrics) and graceful shutdown. * The official package repositories for the distribution. * Security updates current to the image release date. ## Default credentials Once the VM is running, open the VM detail page → **Overview → Connection Details** for the exact username and sign-in method: | VM | How you sign in | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Linux, deployed with an SSH key | **SSH Key Connection** — the username, host, and a ready-to-copy SSH command. Use the private key that matches the selected key. | | Linux, deployed without an SSH key | **SSH Connection** — the username, host, and password. | | Windows | **Remote Desktop (RDP)** — the IP address, the `Administrator` username, and the password. | Passwords are shown only to members with write access while the VM is running. Use the eye icon to reveal a password and the copy button to copy it. To change access later on a Linux VM, open **Settings → Access**. There you can add or remove SSH keys, turn **Password Login** on or off, and **Reset Password**. The VM must be running. For Windows, manage passwords and users inside Windows after connecting over RDP. See [Change access on an existing VM](/docs/tools/ssh-keys#change-access-on-an-existing-vm). ## Switching OS Changing the OS of an existing VM isn't available in the portal yet — **Settings → Change OS** shows "This section is under development." To move to a different OS today, deploy a new VM with the template you need, migrate your data, and delete the old VM. Keep data you want to carry over on a [block storage volume](/docs/infrastructure/block-storage), which you can detach and reattach to the new VM. ## ISOs, snapshots, and backups For non-template installs: * **ISOs** — see [ISOs](/docs/tools/isos) for adding an ISO, and [Custom images](/docs/infrastructure/cloud-vms/custom-images#isos) for the current console limitation. * **Snapshots** — see [Restore a snapshot](/docs/tools/snapshots/restore-a-snapshot). * **Backups** — see [Restore from backup](/docs/tools/backups/restore-from-backup). ## Related pages * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Custom images](/docs/infrastructure/cloud-vms/custom-images) * [SSH keys](/docs/tools/ssh-keys) --- title: Custom images url: https://ibee.ai/docs/infrastructure/cloud-vms/custom-images description: Boot a Cloud VM from your own ISO, a snapshot, or a backup recovery point. last_updated: 2026-10-26 --- # Custom images > Boot a Cloud VM from your own ISO, a snapshot, or a backup recovery point. In addition to IBEE-curated [OS templates](/docs/infrastructure/cloud-vms/os-images), you can deploy a Cloud VM from a **custom image** — your own ISO, a snapshot you've taken from another VM, or a backup recovery point. This is the right path for: * **Golden images** — standardize a build (web server, ML toolchain, security agent) and clone it across many VMs. * **Disaster recovery** — restore a VM from a previous recovery point. * **Niche operating systems** — boot from an ISO not in the template catalog (see the console limitation below). ## Sources The **Operating System** picker on the Deploy page exposes three custom-image tabs: ### ISOs Boot the VM from an ISO you added under **Tools → ISOs**. The **ISOs** tab lists the ISOs available to your account. > **Warning** > > **Interactive installs need a console, which isn't available in the portal yet.** A VM booted from an installer ISO waits for you to step through the installer, and browser console access is still **Coming soon**. Until it ships, use a [template](/docs/infrastructure/cloud-vms/os-images), or a snapshot or backup of a VM you've already built. See [ISOs](/docs/tools/isos) for adding ISOs and attaching or detaching them. ### Snapshots Manual recovery points captured from another VM ([Create a snapshot](/docs/tools/snapshots/create-a-snapshot)). When you select a snapshot: * The root disk is cloned to a new disk on the new VM. * Any captured data volumes from the snapshot set are also restored and **auto-attached** to the new VM. * For data volumes, mount instructions are surfaced in the snapshot detail view ([Restore a snapshot](/docs/tools/snapshots/restore-a-snapshot)). Use snapshots when you need an exact, point-in-time clone — including filesystem state — and you control when the snapshot was taken. ### Backups Scheduled recovery points produced by the [automated backups](/docs/tools/backups/enable-backups) feature. Deploying from the **Backups** tab uses the captured **root disk only**. To restore the root and attached data disks together, open the source VM's **Backups** tab and choose **Create New VM** instead. See [Restore from backup](/docs/tools/backups/restore-from-backup). ## When to choose each source | Source | Best for | Notes | | ------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **ISO** | OS not in template catalog; clean install with custom partitioning | Needs an interactive console, which isn't available in the portal yet. | | **Snapshot** | Cloning a known-good build to many VMs; pre-cutover migration testing | You control the timing and scope (root only, all volumes, or selective). | | **Backup** | Disaster recovery; rolling back to a recent automated point | Schedule-driven; convenient because it runs without action. | ## Deployment flow 1. Open **Infrastructure → Cloud VMs** and click **Deploy VM**. 2. Pick the **Location** and **Plan** as usual. 3. Under **Operating System**, switch to **ISOs**, **Snapshots**, or **Backups**. 4. Pick the source from the list. The bottom bar updates to show the selected image. 5. Continue with **SSH Keys**, **Network Configuration**, **Billing**, and **VM Details**, then click **Deploy**. See [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) for every field. ## Bring-your-own-image checklist If you build an image yourself, verify before booting: * **virtio drivers** for disk and network are present (Linux) or installed (Windows). KVM uses `virtio-blk` / `virtio-net` by default. * **cloud-init** (Linux) is installed and enabled — needed for SSH key injection and hostname configuration. * **DHCP client** is enabled on the primary NIC — public IPs are assigned via DHCP. * **qemu-guest-agent** is installed if you want guest filesystem metrics. * The **bootloader** points at the right disk (`/dev/vda` for the root disk on KVM). If any of these are missing, the VM may boot but be unreachable, or fail to come up at all. Browser console access isn't available yet, so check [Activity logs](/docs/platform-fundamentals/activity-logs) and the VM's firewall group, or rebuild from a known-good snapshot. ## Related pages * [OS images](/docs/infrastructure/cloud-vms/os-images) * [ISOs](/docs/tools/isos) * [Snapshots](/docs/tools/snapshots) * [Backups](/docs/tools/backups) --- title: Resize a VM url: https://ibee.ai/docs/infrastructure/cloud-vms/resize-a-vm description: Move a Cloud VM to a different plan — upgrade CPU, RAM, and disk, or downgrade CPU and RAM — without rebuilding. last_updated: 2026-10-19 --- # Resize a VM > Move a Cloud VM to a different plan — upgrade CPU, RAM, and disk, or downgrade CPU and RAM — without rebuilding. You can move a Cloud VM to a different plan from **Settings → Change Plan**. The VM is briefly stopped, resources are changed in place, and it restarts on the new plan. Upgrades can grow CPU, RAM, and disk; downgrades can reduce CPU and RAM but never shrink the disk. > **Info** > > **Settings tab availability.** **Change Plan**, **IPv4 & Reserved IP**, **VPC Networks**, and **Access** are available. **Change OS** and **Hostname** show "This section is under development" — changing the OS or hostname of an existing VM isn't available in the portal yet. Set the hostname inside the guest, or deploy a new VM with the OS you need. ## When to resize * CPU sustained near 100% over the **24h** range in [Monitoring](/docs/infrastructure/cloud-vms/monitoring). * Memory pressure: high used / total ratio with no free RAM. * Disk full on the root volume and you don't want to attach a separate [Block Storage](/docs/infrastructure/block-storage) volume. * The VM is consistently over-provisioned and a smaller CPU/RAM plan would do. If only data is growing, attaching a block storage volume is usually a better fit than resizing the whole plan. ## Before you begin * You need write access to the workspace — read-only members see the current plan but not **Change Plan**. * The dropdown lists the other plans available in the VM's region. * Root disks can't shrink. A plan with a smaller disk than the VM's current disk is blocked. ## Steps ### 1. Open Settings On the VM detail page, open the **Settings** tab. **Change Plan** is selected by default. ### 2. Review your current plan The **Current Plan** card shows your existing vCPU, RAM, and disk. ### 3. Pick a plan Open the **Available Upgrades** dropdown and select a plan. Each entry shows the plan name and its vCPU, RAM, and disk. The count above the dropdown tells you how many plans are available for the region. After selection, a **Selected Plan** summary confirms the new specs, and a **Billing term** selector lets you choose the term for the new plan (the options depend on the plan). ### 4. Confirm the change What you see next depends on the target plan: | Target plan | What the portal shows | Button | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | Larger CPU, RAM, or disk | **Upgrade Process** — the server is briefly stopped, CPU, RAM, and disk are upgraded, it restarts automatically, and billing moves to the new rate. | **Upgrade Plan** | | Less CPU or RAM, same or larger disk | **Downgrade Process** — the server is stopped, CPU and RAM are adjusted, the disk stays at its current size, the server restarts, and billing is adjusted. | **Downgrade Plan** | | Smaller disk | **Downgrade Not Possible** — disk shrinking isn't supported because it risks data loss. | — | Click **Upgrade Plan** or **Downgrade Plan**. The portal shows **Verifying…** while it checks the resize. If the resize can't be done in place, a **Resize not possible** message lists the reasons. ### 5. Confirm the resize In the **Confirm Resize** dialog, review the current and target vCPU, RAM, and disk, plus the **Downtime notice**, then click **Confirm Resize**: * A running VM is stopped, resized, and started automatically. * A stopped VM is resized without being started. ## What changes | Resource | Behavior | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **vCPU / RAM** | Updated during the brief stop. | | **Root disk** | Grows to the new plan's size on an upgrade; stays the same on a CPU/RAM downgrade. You may need to extend the filesystem inside the guest if it doesn't auto-grow (see below). | | **Public IP** | Preserved. | | **Attached volumes** | Preserved and remain attached. | | **Snapshots / backups** | Preserved. | | **Hostname / SSH keys** | Preserved. | ## Extend the root filesystem (Linux) Most cloud images use `cloud-initramfs-growroot` and resize automatically on boot. If `df -h /` still shows the old size after resize, run: ```bash # Identify the root device lsblk # Grow the partition (adjust device/partition number) sudo growpart /dev/vda 1 # Extend the filesystem sudo resize2fs /dev/vda1 # ext4 sudo xfs_growfs / # XFS ``` Reboot if any tool reports the partition is busy. ## Downgrade You can downgrade CPU and RAM in place with **Downgrade Plan**, as long as the target plan's disk is at least as large as the current disk. To move to a plan with a **smaller disk**: 1. Deploy a new VM on the smaller plan ([Create a VM](/docs/infrastructure/cloud-vms/create-a-vm)). 2. Migrate your data to the new VM. 3. Cut DNS over to the new VM and delete the old one when verified. ## Use the API Check first with `POST /compute/cloud-vms/{vm_id}/actions/resize/precheck`, then resize with `POST /compute/cloud-vms/{vm_id}/actions/resize`, giving the target `cpu`, `ram_mb`, and `disk_gb`. The API also has `PATCH /compute/cloud-vms/{vm_id}/actions/resize-plan` (CPU and memory only) and `PATCH /compute/cloud-vms/{vm_id}/actions/resize-root-disk` (grow the root disk only), which the portal doesn't offer. GPU VMs use the same paths under `/compute/gpu-vms`. Picking a plan and billing term, as **Change Plan** does, is portal-only. ## Troubleshooting **No alternative plans available for this region** The VM's region has no other plan to move to. Check [Regions and locations](/docs/getting-started/overview/regions-and-locations) for plan availability. **Resize not possible** The pre-check found a blocker and lists the reasons under the dropdown. Resolve them, or pick a different plan. **Resize stuck** Check [Activity logs](/docs/platform-fundamentals/activity-logs) for a failed resize and its reason. **Disk space didn't grow** Run the `growpart` / `resize2fs` commands above. Some images don't auto-extend on resize. ## Related pages * [Instance types](/docs/infrastructure/cloud-vms/instance-types) * [Power actions](/docs/infrastructure/cloud-vms/power-actions) * [Block Storage](/docs/infrastructure/block-storage) * [Snapshots](/docs/tools/snapshots) --- title: Power actions url: https://ibee.ai/docs/infrastructure/cloud-vms/power-actions description: Start, stop, reboot, and delete IBEE Solutions VMs safely, and what to use while browser console access is unavailable. last_updated: 2026-10-19 --- # Power actions > Start, stop, reboot, and delete IBEE Solutions VMs safely, and what to use while browser console access is unavailable. Power actions live behind the **Actions** menu on the VM detail page, and as inline icons on the **Cloud Virtual Machines** list. Each action is recorded in [Activity logs](/docs/platform-fundamentals/activity-logs). ## Where to find them | Surface | Available actions | | ------------------------------------------- | ------------------------------------------------------------------------------------- | | VM detail page → **Actions** menu | Start · Stop · Reboot · Delete | | **Cloud Virtual Machines** list → row icons | Restart · Delete (the **Console** icon is shown but disabled — "Console coming soon") | Actions that don't apply to the VM's current state are disabled — for example, **Start** on a running VM. Members with read-only access don't see the write actions. ## Actions ### Start Powers on a stopped VM. Boot completes when the VM appears as **Running** in the list and the IP responds to traffic. ### Stop Gracefully shuts down a running VM by signalling ACPI poweroff to the guest. The VM transitions through **Stopping** to **Stopped**. Stopped VMs retain their disks, IP, and configuration. On **Hourly** billing, stopped VMs stop incurring compute charges (storage continues to be billed); **Monthly** and **Yearly** commitments are fixed for the commitment term. > **Warning** > > If the guest does not honor the ACPI signal, the platform will force power-off after a timeout. Long-running workloads should drain or quiesce before you stop the VM. ### Reboot Restarts the VM in place. This is equivalent to a `reboot` issued inside the guest — the kernel boots fresh, but disks, IP, and plan stay the same. Use **Reboot** after kernel upgrades or to clear a stuck process when SSH is unresponsive but the host is healthy. The list's **Restart** icon does the same. ### Console Browser console access isn't available in the portal yet — the **Console** control is shown as **Coming soon**. Until it ships, use these instead: * **Sign-in details** — **Overview → Connection Details** shows the SSH command, or the username and password for password-based Linux VMs and Windows (RDP). * **Lost SSH access (Linux)** — on **Settings → Access**, add another saved SSH key, or reset the OS password and turn on password login. The VM must be running. * **Locked out by a firewall** — fix the firewall group's rules on the [Firewalls](/docs/network-security/firewalls) page. * **Guest won't boot** — reboot the VM, or create a new VM from a [snapshot](/docs/tools/snapshots/restore-a-snapshot) or [backup](/docs/tools/backups/restore-from-backup). ### Delete Permanently removes the VM and its root disk. Open **Delete** from the **Actions** menu or the list's row icon. In the **Delete Virtual Machine** dialog: 1. **Type the VM name** exactly to confirm (use the copy button next to the name). 2. **Attached data volumes** — if any are attached, the dialog warns that they will be **detached automatically**. The volumes and their data are kept in [Block Storage](/docs/infrastructure/block-storage). Unmount them inside the VM first to avoid filesystem corruption. 3. **Public IP** — if the VM has a public IP that isn't already a Reserved IP, choose whether to keep it: * Check **Reserve public IP \
** to keep the address as a [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) named after the VM. Reserved IP billing continues. * Leave it unchecked to release the address. If the address is already a Reserved IP, the dialog confirms it will be kept — it's detached from the VM and stays in **Reserved IPs**. 4. Click **Delete VM**. > **Warning** > > **Delete is irreversible.** Snapshots and backups taken before deletion are retained according to their own retention policy and can be used to recover into a new VM, but the original VM cannot be restored in place once deleted. Before deleting, consider: * Take a final [snapshot](/docs/tools/snapshots/create-a-snapshot) if you might need the data. * Unmount attached block storage volumes inside the guest. * Note the IP if a third-party DNS provider points to it, or reserve it in the delete dialog. ## Status reference | Status | Meaning | | --------------------------- | ----------------------------------------------------------- | | **Provisioning** | Initial deployment in progress. | | **Running** | VM is booted and reachable. | | **Stopping** / **Starting** | Transient state during a power action. | | **Stopped** | Powered off; disks retained. | | **Rebooting** | Restart in progress. | | **Error** | The last operation failed. Check Activity logs for details. | ## CLI and API Start, stop, reboot, and delete are exposed through the public API and the `ibee` CLI. Replace `VM_ID` with the ID from `ibee vms list`: ```bash # Start ibee vms start VM_ID --wait # Stop ibee vms stop VM_ID --wait # Reboot ibee vms reboot VM_ID --wait # Delete without an interactive confirmation (releases an auto-assigned public IP) ibee vms delete VM_ID --yes --wait ``` The API operations are `POST /compute/cloud-vms/{vm_id}/actions/start`, `.../actions/stop`, `.../actions/reboot`, and `DELETE /compute/cloud-vms/{vm_id}` (GPU VMs: the same paths under `/compute/gpu-vms`). Deleting a VM whose public IP was assigned automatically needs a JSON body that says what to do with the address, as the portal's **Reserve public IP** checkbox does: | Field | Value | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `public_ip_action` | `release` to release the address, or `reserve` to keep it as a Reserved IP. Required when the VM has an automatically assigned public IP. | | `reserved_ip_label` | Optional label for the new Reserved IP (up to 120 characters). | | `reserved_ip_billing_catalog` | Required with `reserve`: the Reserved IP's billing catalog entry, with its `sku_id`. | The portal has no console yet, but the public API can open a short-lived graphical console session for a cloud or GPU VM with `POST /compute/console/sessions`. Check it with `GET /compute/console/sessions/{session_id}` and close it with `DELETE /compute/console/sessions/{session_id}`. The returned connect URL contains an expiring token — don't log or store it. ## Troubleshooting **VM stuck in `Stopping`** The guest may be ignoring the shutdown request. Wait a few minutes, then check [Activity logs](/docs/platform-fundamentals/activity-logs). If it doesn't recover, contact [IBEE support](/docs/support/contact-support). **Delete or Reboot is disabled** Another operation (for example a backup, snapshot, or resize) is in progress — the row icons show **Operation in progress...**. Wait for it to finish, then try again. **Can't connect after a change** Browser console access isn't available yet. Check **Overview → Connection Details**, the VM's firewall group, and **Settings → Access**, as described under [Console](#console). ## Related pages * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Monitoring](/docs/infrastructure/cloud-vms/monitoring) * [Snapshots](/docs/tools/snapshots) * [Backups](/docs/tools/backups) --- title: Networking for VMs url: https://ibee.ai/docs/infrastructure/cloud-vms/networking-for-vms description: How public IPs, VPCs, NAT, Reserved IPs, firewall groups, and bandwidth work for IBEE Solutions VMs. last_updated: 2026-10-19 --- # Networking for VMs > How public IPs, VPCs, NAT, Reserved IPs, firewall groups, and bandwidth work for IBEE Solutions VMs. You choose how a Cloud VM connects to the network when you deploy it, and you can change most of it later from the VM's **Settings** tab. This page explains the options, the defaults, and the controls available to you. ## Network modes at deploy time On the Deploy page, **Network Configuration → VM network → Internet and VPC access** offers three modes: | Mode | Primary interface | Internet access | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | **Public IP** *(default)* | The platform network (**No VPC · public interface only**), or a VPC you select. With a VPC, the public IP maps to the VM's VPC private IP. | Direct inbound and outbound IPv4. | | **Private + NAT** | A NAT Gateway VPC. | Managed outbound internet; inbound internet is blocked. | | **Private only** | A VPC. | None. | When you select a VPC you must also select a **Subnet**. Only VPCs compatible with the chosen mode in the VM's location are listed. See [VPC](/docs/network-security/vpc-ip-management) to create VPCs and subnets. ### Reserved public IP With **Public IP**, a **Reserved public IP** field appears — with a VPC, or with **No VPC · public interface only**: * **Allocate automatically** — the platform assigns an address. This is the default unless the VPC is private. * **A Reserved IP you own** — pick an unattached one from the same location. Required when the VPC is **private**; create one first under [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips) if the list is empty. A specific Reserved IP can be attached to one VM at a time, so selecting one limits the deployment to a single VM. ## Default network setup | Property | Default | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | Public IPv4 | One address assigned at deploy time with **Public IP** mode. **Private + NAT** and **Private only** VMs have no public IP. | | DHCP | Enabled on the primary interface (`eth0` / `ens3`) | | Firewall | The default firewall group, unless you select another group at deploy time | | Inbound bandwidth | Unmetered | | Outbound bandwidth | Per-plan allowance (see [Instance types](/docs/infrastructure/cloud-vms/instance-types)) | The **Cloud Virtual Machines** list shows the assigned address under the **IP Address** column once provisioning completes (for example `103.149.10.116`). ## Inside the guest The primary NIC uses `virtio-net`. Most cloud images bring the interface up automatically via DHCP at boot. To check: ```bash ip -4 addr show ip route ``` On a **Public IP** VM without a VPC, you should see the public IP on the primary interface and a default route via the IBEE gateway. On a VPC-attached VM, you see the VPC private IP. ## Firewalls Every VM is protected by a firewall group that controls inbound access: * At deploy time, pick a group under **Network Configuration → Firewall**, or click **Create Group** to create one and select it. * If you don't select a group, the **default firewall group is attached automatically**. * Add or edit rules on the [Firewalls](/docs/network-security/firewalls) page — see [Create firewall rules](/docs/network-security/firewalls/create-firewall-rules). Check the attached group's rules if a service isn't reachable. Inside the guest, you can also run `ufw`, `firewalld`, or Windows Defender Firewall — they stack with the platform firewall. ## Change networking after deploy Open the VM detail page → **Settings**: ### IPv4 & Reserved IP Shows the VM's public address and how it's managed: * **Main VM address** — the provider-assigned address is **Managed with VM**. If the VM also has a NAT VPC as its default route, **Keep as Reserved** opens **Remove direct public network**: the address is kept as a Reserved IP for later reuse, and the VM switches to its NAT VPC interface for outbound internet. Direct inbound traffic to the address stops, so add a NAT port-forwarding rule for services that must stay reachable. * **Attach IP** / **Attach or Move IP** — attach one of your same-location Reserved IPs, or move one from another VM. A Reserved IP can be attached to one VM at a time. * **Detach IP** — public traffic to that address stops; the address stays in **Reserved IPs**. * **Repair network** — shown only for an older VM that has no active network interface. Click it to repair the VM's provider network, then attach a Reserved IP. When you delete a VM, the delete dialog also offers to keep its public IP as a Reserved IP — see [Power actions](/docs/infrastructure/cloud-vms/power-actions#delete). ### VPC Networks Lists the VPC interfaces attached to the VM, with each interface's private IP, subnet, and VPC ID: * **Attach VPC** — connect the VM to a VPC and subnet in the same site. In the panel, pick the **VPC** and **Subnet**, choose **Private IP assignment** (**Automatic**, or **Specific address** for an unused host address in the subnet), check **Traffic routing**, then click **Attach VPC**. If the VM has no network yet, the VPC becomes its primary network. If it already has one, the new VPC carries private traffic only — except a NAT VPC, where you can choose **Use VPC for internet** (the VPC becomes the default route; the current public IP stays until you remove it under **IPv4 & Reserved IP**) or **Private traffic only**. * **Detach VPC** — remove a VPC interface. A VM must always keep at least one network interface, so the primary interface can't be detached until another route is in place. The guest may need network configuration after the change. ## Connecting to private VMs **Private + NAT** and **Private only** VMs can't accept direct connections from the internet. **Overview → Connection Details** shows the private SSH or RDP command to use from inside the VPC — for example through a VPN, a bastion host, or another VM in the VPC. NAT VMs can also use a NAT port-forward rule for inbound access. ## DNS Use any DNS provider to point a domain at your VM: 1. Add an `A` record for the VM's public IP. 2. Add a `CNAME` for `www` if needed. A [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) keeps the address stable if you later replace the VM. ## Bandwidth and overage Each plan includes a monthly outbound bandwidth allowance (for example **2 TB** on `std.1.c2.m8`). The Monitoring tab's **Network Traffic** chart shows current inbound and outbound throughput and your monthly outbound usage. * Inbound traffic is unmetered. * Outbound usage above the included allowance is billed per GB; see your plan summary for the rate. ## Load balancing To put a load balancer in front of multiple VMs, use [Load Balancer](/docs/network-security/load-balancer): * Create the load balancer in the same region as your VMs. * Attach the VMs as backends and configure a health check. * Optionally terminate TLS at the load balancer. ## Troubleshooting **VM has no public IP after deploy** **Private + NAT** and **Private only** VMs don't get a public IP — this is expected. For **Public IP** VMs, refresh the list; the column updates after provisioning completes. If it stays blank for more than a few minutes, check [Activity logs](/docs/platform-fundamentals/activity-logs) for a failed create. **Can't SSH but the VM is Running** * Check that the VM's firewall group allows port 22 from your address. * Confirm you're using the username and host from **Overview → Connection Details**. * If the key is wrong or lost, add another saved key, or reset the password and enable password login, on **Settings → Access**. Browser console access isn't available in the portal yet. **Deploy says a Reserved IP is required** You chose **Public IP** with a **private** VPC. Create a Reserved IP in the same location, or pick a public VPC or **No VPC**. **Bandwidth chart looks flat or empty** The chart smooths over its time range. Switch to **30m** for short-window detail. ## Related pages * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [VPC](/docs/network-security/vpc-ip-management) * [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips) * [Firewalls](/docs/network-security/firewalls) * [Load Balancer](/docs/network-security/load-balancer) --- title: Attach volumes url: https://ibee.ai/docs/infrastructure/cloud-vms/attach-volumes description: Add Block Storage volumes to a Cloud VM and mount them inside the guest. last_updated: 2026-10-19 --- # Attach volumes > Add Block Storage volumes to a Cloud VM and mount them inside the guest. Attach a [Block Storage](/docs/infrastructure/block-storage) volume to a Cloud VM when you need persistent storage that survives plan changes and VM deletion (deleting a VM detaches its data volumes automatically and keeps them). Volumes attach as additional disks (`vdb`, `vdc`, …) alongside the root disk (`vda`). ## When to use a separate volume * Your data should outlive the VM (databases, file servers, user uploads). * You want to grow capacity independently of CPU and RAM. * You need to move data between VMs (detach from one, attach to another). * You want snapshot scope flexibility — capture data volumes selectively ([Selective volumes capture mode](/docs/tools/snapshots/create-a-snapshot)). For ephemeral data that lives and dies with the VM, the included root disk on each [instance type](/docs/infrastructure/cloud-vms/instance-types) is fine. ## Attach a volume ### 1. Create the volume If you don't already have one, create a volume in the **same region** as the VM. See [Create a volume](/docs/infrastructure/block-storage/create-a-volume). ### 2. Attach from Block Storage Volumes are attached from the **Block Storage** page — the VM detail page doesn't have a volumes section. Open **Block Storage**, click the volume, then click **Attach to Server** and pick the VM. See [Attach and detach a volume](/docs/infrastructure/block-storage/attach-and-detach-a-volume) for the full steps. ### 3. Wait for the attachment to complete When the attachment finishes, the volume shows the VM as attached in **Block Storage**, and it appears as a new block device inside the guest. The operation is also recorded in [Activity logs](/docs/platform-fundamentals/activity-logs). ## Mount the volume inside the guest (Linux) Use the commands on the volume's **Mount Instructions** tab in **Block Storage**, or follow these standard steps the first time you attach a fresh volume. ```bash # 1. Confirm the new device lsblk # 2. (First time only) Create a filesystem sudo mkfs.ext4 /dev/vdb # 3. Create a mount point sudo mkdir -p /mnt/volume_ # 4. Mount it sudo mount /dev/vdb /mnt/volume_ # 5. Persist across reboots — use UUID for stability echo "UUID=$(blkid -s UUID -o value /dev/vdb) /mnt/volume_ ext4 defaults 0 0" | sudo tee -a /etc/fstab ``` > **Warning** > > **Use UUID-based fstab entries.** Device names like `/dev/vdb` can change after detach/reattach or restore. Mounting by UUID keeps the path stable. After a restore, the recovery point's **Details** view (on the VM's **Snapshots** or **Backups** tab) shows **Mount Instructions** for each restored data volume. A restored volume already has a filesystem — mount it, don't format it. ## Mount the volume inside the guest (Windows) 1. Open **Disk Management**. 2. Bring the new disk **Online** and **Initialize** it (GPT for >2 TB). 3. Right-click the unallocated space → **New Simple Volume** and follow the wizard. 4. Assign a drive letter and format as NTFS. ## Detach a volume 1. Unmount inside the guest first (`sudo umount /mnt/volume_`) to avoid filesystem corruption. 2. On the volume's **Block Storage** page, click **Detach**. 3. Wait for the volume to show as detached in **Block Storage**. A detached volume keeps its data and can be reattached to any VM in the same region. ## Volumes and snapshots When you take a snapshot, you choose the **Capture Mode**: | Mode | What's captured | | ------------------------ | ----------------------------------------------------------------- | | **Root volume only** | Just the boot disk. Attached data volumes are skipped. | | **All attached volumes** | Root disk plus every attached data volume. | | **Selective volumes** | Root is always included; pick which attached data volumes to add. | After restore, captured data volumes are auto-attached to the target VM. Mount instructions are surfaced in the snapshot detail view. See [Create a snapshot](/docs/tools/snapshots/create-a-snapshot). ## Troubleshooting **`lsblk` doesn't show the new device** Wait 10–20 seconds after the attachment completes, then rerun. If it still doesn't appear, reboot the VM. **`mount` fails with "wrong fs type"** The volume isn't formatted yet. Run `sudo mkfs.ext4 /dev/vdX` on the **first** attach only. **Volume is read-only after restore** The platform restores the volume but doesn't mount it inside the guest. Use the **Mount Instructions** in the recovery point's **Details** view for that volume. ## Related pages * [Block Storage overview](/docs/infrastructure/block-storage) * [Create a volume](/docs/infrastructure/block-storage/create-a-volume) * [Attach and detach a volume](/docs/infrastructure/block-storage/attach-and-detach-a-volume) * [Create a snapshot](/docs/tools/snapshots/create-a-snapshot) --- title: Monitoring url: https://ibee.ai/docs/infrastructure/cloud-vms/monitoring description: Track CPU, memory, disk, and network metrics for your Cloud VM, and find its recent operations in Activity logs. last_updated: 2026-10-19 --- # Monitoring > Track CPU, memory, disk, and network metrics for your Cloud VM, and find its recent operations in Activity logs. The **Monitoring** tab on the server detail page shows live metrics for the VM. Use it to spot saturation, validate resize impact, and see the load of backup or snapshot windows. ## Open monitoring 1. Go to **Cloud VMs** in the IBEE Solutions portal. 2. Click your VM to open the detail page. 3. Open the **Monitoring** tab. The header shows when metrics were last updated and the sample interval (typically **1-minute intervals**). Use the time range buttons to switch between **30m**, **1h**, **6h**, **24h**, and **7d**. Click **Refresh** to force an immediate sample. ## Compute metrics | Metric | Source | What it shows | | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | **CPU Utilization** | Host-side libvirt | VM CPU % across all allocated vCPUs. Spikes above the plan's vCPU count indicate steal pressure. | | **Memory Utilization** | Host-side libvirt (when available) | Memory used vs. allocated, in MB. Falls back to balloon stats when the guest agent is unavailable. | A current value and last sample timestamp are shown above each chart. ## Storage and disk metrics | Metric | Source | What it shows | | ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- | | **Storage Utilization** | QEMU guest agent | Guest filesystem usage as a percentage and absolute used/total. Requires the guest agent to be installed. | | **Disk Throughput** | libvirt block counters | Read and write throughput (B/s, KB/s, MB/s). | | **Disk IOPS** | libvirt block counters | Read and write operations per second. | If **Storage Utilization** is missing, install or start `qemu-guest-agent` inside the VM: ```bash sudo apt-get install -y qemu-guest-agent sudo systemctl enable --now qemu-guest-agent ``` Throughput and IOPS metrics work without the guest agent. ## Network metrics The **Network Traffic** chart plots **inbound** and **outbound** traffic per second, with the current rates and your **Monthly outbound** usage shown above it. Use it together with the bandwidth allowance for your plan ([Instance types](/docs/infrastructure/cloud-vms/instance-types)) to estimate monthly egress. ## Recent activity The Monitoring tab shows metrics only. To see what was done to a VM — create, power actions, volume changes, snapshots, restores — and whether each operation succeeded, open **Activity Logs** under **Organization** in the portal sidebar. See [Activity logs](/docs/platform-fundamentals/activity-logs). ## Use the API The same metrics are in the public API (GPU VMs use the same paths under `/compute/gpu-vms/{vm_id}`): * `GET /compute/cloud-vms/{vm_id}/metrics` — current values. * `GET /compute/cloud-vms/{vm_id}/metrics/timeseries` — time series for a range. * `GET /compute/cloud-vms/{vm_id}/metrics/bandwidth` — monthly bandwidth. * `GET /compute/cloud-vms/{vm_id}/events` — the VM's recent events (API only). ## Tips * Investigate **CPU sustained above 80%** before resizing — many workloads are I/O- or memory-bound. * A flat **Memory Utilization** line near 100% with low free RAM is a strong signal to upsize. * If **Disk Throughput** plateaus while CPU has headroom, you may be hitting the disk's IOPS ceiling — consider attaching faster [Block Storage](/docs/infrastructure/block-storage). * Use the **24h** range to see backup or snapshot windows; expect a small CPU and disk bump during those windows. ## Related pages * [Instance types](/docs/infrastructure/cloud-vms/instance-types) * [Resize a VM](/docs/infrastructure/cloud-vms/resize-a-vm) * [Backups](/docs/tools/backups) * [Snapshots](/docs/tools/snapshots) --- title: Object Storage url: https://ibee.ai/docs/infrastructure/object-storage description: IBEE Object Storage is a scalable, S3-compatible storage service for files, media, backups, and application assets. Works with any S3-compatible SDK or tool. last_updated: 2026-10-19 --- # Object Storage > IBEE Object Storage is a scalable, S3-compatible storage service for files, media, backups, and application assets. Works with any S3-compatible SDK or tool. IBEE Object Storage is a scalable object storage service with an S3-compatible API. Use it to store files, media, backups, and application assets — accessible from any S3-compatible SDK, CLI tool, or client. ## Use cases * **Static website hosting** — serve HTML, CSS, and assets directly from a bucket * **Media and asset storage** — store images, videos, and documents for your applications * **Application data and backups** — store database dumps, snapshots, and application exports * **Log archiving** — collect and retain logs at scale * **CDN origin storage** — use a bucket as the origin for CDN-delivered content ## Capabilities | Feature | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------- | | S3-compatible API | Works with AWS SDKs, s3cmd, rclone, and other S3-compatible clients | | S3 credentials | Access Key ID + Secret Access Key per workspace, created under **Organization → API Tokens → S3 Credentials** | | Public Access URL | Serve a bucket publicly without an SDK | | Custom Domains | Front a public bucket with your own hostname | | CORS | Cross-origin browser access rules per bucket | | Lifecycle Policies | Automate object expiry | | Versioning | Keep previous object versions (turned on with Object Lock at bucket creation) | | Object Lock | Make objects immutable for compliance (set at bucket creation), plus per-object retention and legal hold | | Event Notifications | Webhook when objects are uploaded | ## Available regions | Region code | Location | Status | | ----------- | ---------------------- | ------------------------------------------------- | | VGA | Amaravati, India | Available | | HYD | Hyderabad, India | Pre-order — [contact sales](mailto:sales@ibee.ai) | | IAD | Ashburn, United States | Pre-order — [contact sales](mailto:sales@ibee.ai) | ## Where to start #### [Core Concepts](/docs/infrastructure/object-storage/core-concepts) Buckets, objects, regions, endpoints — the building blocks. #### [Upload Your First Object](/docs/infrastructure/object-storage/upload-your-first-object) Create your first bucket, generate API credentials, and upload an object. #### [Buckets](/docs/infrastructure/object-storage/buckets) Containers for objects — settings, policies, lifecycle, CORS, custom domains. #### [Objects](/docs/infrastructure/object-storage/objects) Upload, download, lock, and presign objects. #### [Mount a Bucket as a Filesystem](/docs/infrastructure/object-storage/mount-a-bucket-as-a-filesystem) Access a bucket like a local directory with `s3fs` or `rclone`. #### [Metrics](/docs/infrastructure/object-storage/metrics) Track usage, objects, and bandwidth — organization-wide and per bucket. ## Related pages * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Static Site Hosting](/docs/infrastructure/object-storage/static-site-hosting) * [CDN integration](/docs/infrastructure/object-storage/cdn-integration) * [Pricing](/docs/infrastructure/object-storage/pricing) * [Limits](/docs/infrastructure/object-storage/limits) --- title: Core Concepts url: https://ibee.ai/docs/infrastructure/object-storage/core-concepts description: Core building blocks of IBEE Object Storage — buckets, objects, regions, endpoints, and access. last_updated: 2026-10-19 --- # Core Concepts > Core building blocks of IBEE Object Storage — buckets, objects, regions, endpoints, and access. Before working with Object Storage it helps to understand the building blocks: **buckets**, **objects**, **regions**, **endpoints**, and **access** via API Credentials. ## Buckets A **bucket** is a container for objects. Every object you upload lives in exactly one bucket. * Bucket names are **globally unique** within IBEE Object Storage. * A bucket's **location** is fixed at creation and cannot be changed — to use a different location, create a new bucket and migrate your objects. * Use multiple buckets to separate environments, projects, or access boundaries. Bucket names must be **3 to 63 characters**, lowercase, and contain only letters, numbers, and hyphens. They must start and end with a letter or number. See [Buckets](/docs/infrastructure/object-storage/buckets) for the full naming rules and the create flow. ## Objects An **object** is a single file plus its metadata. Each object has: * A **key** — the path-like name within the bucket (`reports/2026-05.pdf`). * The object **data** — up to 5 TiB per object. * A **type** (MIME type, e.g. `image/jpeg`) and **storage class** (`Standard`). * System metadata — size, last-modified, ETag. There's no real folder hierarchy — only keys with `/` separators. The portal renders prefixes as folders. See [Objects](/docs/infrastructure/object-storage/objects) for upload, download, and management. ## Regions A **region** is a physical data center where buckets live. Pick the region closest to your users or your compute. | Region | Code | Status | | ---------------- | ----- | --------- | | Amaravati, India | `VGA` | Available | | Hyderabad, India | `HYD` | Preorder | | Ashburn, USA | `IAD` | Preorder | When creating a bucket, keep **Automatic location** to let the platform pick the best available region, or click **Need a specific location? click here** to choose a site yourself. Pre-order sites show **Talk to Sales** instead of a create button. Jurisdiction-based placement (**Specify jurisdiction**) is coming soon — talk to sales if you need it today. See [Buckets → Create a bucket](/docs/infrastructure/object-storage/buckets#create-a-bucket) and [Regions & Locations](/docs/getting-started/overview/regions-and-locations). ## Endpoints The **endpoint** is the HTTPS URL S3-compatible clients connect to. Each workspace has its own S3 endpoint: ```text https://{workspaceId}.blob.ibeestorage.com ``` Use this with the AWS CLI, AWS SDKs, `s3cmd`, `rclone`, or any S3-compatible tool — paired with the Access Key ID and Secret Access Key from an [API Credentials](/docs/infrastructure/object-storage/api-tokens). For browser delivery from a public bucket, use the bucket's **Public Access URL** or a **Custom Domain** instead. See [Buckets → Policies](/docs/infrastructure/object-storage/buckets/bucket-policies) and [Buckets → Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains). ## Access To reach buckets from S3-compatible tools you create an **S3 credential** under **Organization → API Tokens → S3 Credentials**. Each credential belongs to one workspace and gives you: | Credential | Use | | ----------------- | --------------------------------------------------------------- | | Access Key ID | S3-compatible tools (AWS CLI, SDKs, rclone) | | Secret Access Key | S3-compatible tools — shown once only | | S3 Endpoint | `https://{workspaceId}.blob.ibeestorage.com` for that workspace | Permission levels range from `Object Read only` to `Admin Read & Write`. Object-level credentials can be limited to specific buckets; Admin credentials always apply to every bucket in the workspace. See [API Credentials](/docs/infrastructure/object-storage/api-tokens) for the full flow. ## Public access and Object Lock These bucket-level settings control how objects can be read, written, and kept: * **Public Access** — when enabled, objects can be served unauthenticated via the bucket's Public Access URL. Toggled from **Settings → General**. * **Versioning** — keeps previous versions of overwritten or deleted objects. Today it is turned on only when you enable **Object lock (WORM)** at bucket creation; the **Versioning** toggle on its own isn't applied yet. * **Object Lock** — prevents objects from being deleted or overwritten while a retention period is in effect. **Permanent setting** that must be enabled at bucket creation under **Versioning and object lock** (it also turns on versioning). See [Objects → Locking](/docs/infrastructure/object-storage/objects/object-locking). ## Related * [Getting started](/docs/infrastructure/object-storage/upload-your-first-object) * [Buckets](/docs/infrastructure/object-storage/buckets) * [Objects](/docs/infrastructure/object-storage/objects) * [Limits](/docs/infrastructure/object-storage/limits) --- title: Upload Your First Object url: https://ibee.ai/docs/infrastructure/object-storage/upload-your-first-object description: Create your first bucket, generate API credentials, and upload an object — using the IBEE Solutions portal and an S3-compatible client. last_updated: 2026-10-19 --- # Upload Your First Object > Create your first bucket, generate API credentials, and upload an object — using the IBEE Solutions portal and an S3-compatible client. This guide walks through creating a bucket, generating API credentials, and uploading your first object — first from the portal, then from the AWS CLI. ## Before you begin * An active IBEE Solutions organization with a verified account * (Optional) The [AWS CLI](https://docs.aws.amazon.com/cli/) installed locally if you want to upload programmatically ## 1. Create a bucket In the portal, click **Object Storage** in the left sidebar under **Infrastructure**, then click **Create Bucket** at the top right of the Object Storage page. Fill in the create-bucket page: | Field | Value | | ------------------------------ | -------------------------------------------------------------------------------------------------- | | **Bucket name** | 3–63 characters, lowercase letters, numbers, and hyphens only (e.g. `my-first-bucket`). | | **Location** | Keep **Automatic location**, or click **Need a specific location? click here** to pick a site. | | **Storage type** | One of the storage types offered for the location. | | **Versioning and object lock** | Optional. Turn on **Object lock (WORM)** here if you need immutability — it cannot be added later. | Click **Create Bucket**. A confirmation toast appears: *"Bucket created successfully"* and the bucket appears in the list. See [Buckets](/docs/infrastructure/object-storage/buckets) for the full create-bucket reference. ## 2. Upload an object from the portal Click your new bucket from the Object Storage list to open it. The bucket page has three tabs: **Objects**, **Metrics**, **Settings**. On the **Objects** tab, click **Upload** in the top right. Drag and drop a file onto the upload area, or click **Select Files**. The uploaded object appears in the list with its **Type**, **Storage Class**, **Size**, and **Modified** date. > **Info** > > The portal accepts files up to **300 MB** each. Upload larger files with an S3-compatible client (step 4), which uses multipart upload automatically. See [Objects](/docs/infrastructure/object-storage/objects) for full upload, download, and detail-page reference. ## 3. Create API credentials For S3-compatible tools you need an **S3 credential** for the workspace that holds your bucket. In the portal sidebar, click **API Tokens** under **Organization**, open the **S3 Credentials** tab, and click **Create S3 Credential**. (On the Object Storage page, the **S3 API Credentials** button takes you to the same tab.) Give the credential a **Name**, select the **Workspace**, and choose a permission level (e.g. **Admin Read & Write**). For **Object Read & Write** or **Object Read only**, also pick **Apply to all buckets in the selected workspace** or **Apply to specific buckets only**. Click **Create Credential** and copy the values immediately — the **Secret Access Key** is shown only once: | Credential | Use | | ----------------- | -------------------------------------------------------------------- | | Access Key ID | S3-compatible tools | | Secret Access Key | S3-compatible tools — shown once, copy now | | S3 Endpoint | The workspace endpoint, `https://{workspaceId}.blob.ibeestorage.com` | See [API Credentials](/docs/infrastructure/object-storage/api-tokens) for rotation, scoping, and revoke. ## 4. Upload from the AWS CLI Configure a profile with your credentials: ```bash aws configure --profile ibee # AWS Access Key ID: AKIA... # AWS Secret Access Key: # Default region: us-east-1 # Default output: json ``` Upload an object: ```bash echo "hello, IBEE" > hello.txt aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ --profile ibee \ s3 cp hello.txt s3://my-first-bucket/ ``` Verify and download: ```bash # List aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ --profile ibee \ s3 ls s3://my-first-bucket/ # Download aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ --profile ibee \ s3 cp s3://my-first-bucket/hello.txt ./hello-copy.txt ``` ## Next steps #### [Bucket Policies](/docs/infrastructure/object-storage/buckets/bucket-policies) Make a bucket public, scope access by API token. #### [Lifecycle Management](/docs/infrastructure/object-storage/buckets/lifecycle-management) Automate object expiry. #### [Presigned URLs](/docs/infrastructure/object-storage/objects/presigned-urls) Share time-limited links for upload or download. #### [Mount a Bucket as a Filesystem](/docs/infrastructure/object-storage/mount-a-bucket-as-a-filesystem) Use a bucket like a local directory with `s3fs` or `rclone`. --- title: Buckets url: https://ibee.ai/docs/infrastructure/object-storage/buckets description: Containers for objects in IBEE Object Storage. Create buckets, configure settings, and manage their lifecycle. last_updated: 2026-10-19 --- # Buckets > Containers for objects in IBEE Object Storage. Create buckets, configure settings, and manage their lifecycle. A **bucket** is a container for objects. Every object lives in exactly one bucket, and a bucket lives in a single location (chosen at creation). ## What you can do with a bucket #### [Bucket Policies](/docs/infrastructure/object-storage/buckets/bucket-policies) Toggle public access, scope API token access by bucket. #### [Lifecycle Management](/docs/infrastructure/object-storage/buckets/lifecycle-management) Automate object expiry by prefix. #### [CORS](/docs/infrastructure/object-storage/buckets/cors) Allow browser apps from your domains to read or write to the bucket. #### [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) Serve bucket content from your own hostname (e.g. `cdn.example.com`). #### [Event Notifications](/docs/infrastructure/object-storage/buckets/event-notifications) Send a webhook POST when objects are uploaded. ## Naming rules Bucket names must: * Be **3 to 63 characters** long. * Contain only **lowercase letters, numbers, and hyphens (`-`)** — dots (`.`) and underscores (`_`) are not allowed. * Start and end with a **lowercase letter or number**. * Be **globally unique** within IBEE Object Storage. | | Example | | --------- | -------------------------------------------------- | | ✅ Valid | `my-bucket` | | ✅ Valid | `data-store-01` | | ✅ Valid | `project-assets` | | ❌ Invalid | `My-Bucket` — uppercase not allowed | | ❌ Invalid | `-startwithdash` — cannot start with a hyphen | | ❌ Invalid | `endswithdash-` — cannot end with a hyphen | | ❌ Invalid | `bucket_with_underscore` — underscores not allowed | | ❌ Invalid | `project.assets` — dots not allowed | | ❌ Invalid | `ab` — too short (minimum 3 characters) | ## Create a bucket ### 1. Go to Object Storage In the IBEE Solutions portal, click **Object Storage** in the left sidebar under **Infrastructure**. The page lives at `portal.ibee.ai/organizations/{orgId}/workspaces/{workspaceId}/object-storage`. ### 2. Open the create-bucket page Click **Create Bucket** in the top right. The create page has four sections: | Section | Required | Description | | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- | | **Bucket name** | Yes | 3–63 characters, lowercase letters, numbers, and hyphens only. Placeholder: `my-unique-bucket-name`. | | **Location** | Yes | See [Choose a location](#choose-a-location) below. | | **Storage type** | Yes | The storage types offered for the chosen location. | | **Versioning and object lock** | No | **Versioning** and **Object lock (WORM)** toggles. See [Versioning and Object Lock](#versioning-and-object-lock) below. | #### Choose a location The **Location** section has two tabs: * **Automatic** — **Automatic location** (the default) picks the best available region for the bucket. To choose yourself, click **Need a specific location? click here** and pick a site from the grid. Available sites are labelled with their country; pre-order sites are labelled **Talk to Sales**. * **Specify jurisdiction** — coming soon. For jurisdiction-based placement, talk to sales. If you pick a pre-order site or the jurisdiction tab, the footer button changes from **Create Bucket** to **Talk to Sales**. #### Versioning and Object Lock | Toggle | Effect | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Versioning** | Meant to keep previous versions of overwritten or deleted objects. Off by default. On its own this toggle isn't applied yet; versioning is turned on only together with **Object lock (WORM)**. | | **Object lock (WORM)** | Makes objects immutable while a retention period applies. Turning it on also turns on **Versioning**. Permanent — it can only be enabled here, at creation. | With **Object lock (WORM)** on, pick a default retention mode — **None**, **Governance**, or **Compliance** — and, for Governance or Compliance, a **Retention period** in days (default 30, minimum 1). You can change the default retention later on the **Lock Settings** tab. See [Objects → Locking](/docs/infrastructure/object-storage/objects/object-locking). ### API placement For public API requests, omit `site_id`. It is internal placement metadata, not a value users should guess or copy from another product. The `region` field is required and must be the Object Storage region identifier configured for the target environment. Do not send a compute site ID or a display name. The public API does not currently provide a region-discovery endpoint. Use the region identifier provided for your environment; if it is not available in your account configuration, contact support before creating the bucket. Bucket creation requires the `object-storage.write` scope. ### 3. Save Click **Create Bucket**. A toast appears: *"Bucket created successfully"*. ## List buckets The Object Storage page lists every bucket in the organization with these columns: | Column | Description | | ------- | ------------------ | | BUCKET | Bucket name | | SIZE | Total storage used | | CREATED | Creation date | Once you have a bucket, the usage panel at the top shows **Buckets**, **Objects**, **Storage Used**, and **Bandwidth Egress** for the current billing month. Use **Search buckets...** to filter the list. ## Bucket detail page Click a bucket name to open it. The bucket page has three tabs: | Tab | Use | | ------------ | ------------------------------------------------------------------------------------------------------- | | **Objects** | Upload, download, list, and delete objects. See [Objects](/docs/infrastructure/object-storage/objects). | | **Metrics** | Storage and request usage for the bucket. See [Metrics](/docs/infrastructure/object-storage/metrics). | | **Settings** | All bucket-level configuration — see below. | ## Settings tabs **Settings** opens a sub-navigation with these tabs: | Tab | Configures | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **General** | Bucket metadata, **Public Access** toggle, **Public Access URL**, **Object Lock** status, and the **Danger Zone** (Empty bucket, Delete bucket). | | **Lifecycle Policies** | Automatic object expiry. See [Lifecycle](/docs/infrastructure/object-storage/buckets/lifecycle-management). | | **CORS** | Cross-origin browser access rules. See [CORS](/docs/infrastructure/object-storage/buckets/cors). | | **Lock Settings** | Object Lock retention (only if Object Lock was enabled at creation). | | **Event Notifications** | Webhook notifications for object uploads. See [Event Notifications](/docs/infrastructure/object-storage/buckets/event-notifications). | | **Custom Domains** | Serve content from your own hostname. See [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains). | The **General** tab fields: | Field | Description | | ------------- | --------------------------------------------- | | Name | Bucket name | | Created | Creation date | | Total Objects | Number of objects in the bucket | | Storage Used | Total storage consumed | | Public Access | Toggle — Disabled by default | | Object Lock | Read-only state — set permanently at creation | ## Empty a bucket **Empty bucket** permanently removes every object in a bucket while keeping the bucket and its settings. It runs as a background job, so you don't have to delete objects one by one. ### Open the Danger Zone Open the bucket → **Settings** → **General**. The **Danger Zone** card at the bottom holds **Empty bucket** and **Delete bucket**. ### Start the job Click **Empty bucket**. In the dialog, type the bucket name to confirm and click **Empty bucket**. *This action cannot be undone.* ### Track progress A status strip replaces the button while the job runs — for example *Emptying bucket…*, *Finalizing empty bucket…*, or *Retrying empty bucket…*. Click **Cancel** to stop a running job. When it finishes, the strip shows the outcome (*Bucket contents were deleted*, *Bucket partially emptied*, *Some objects are protected*, *Couldn't empty bucket*, or *Empty bucket cancelled*) and can be dismissed. > **Warning** > > **Empty bucket isn't available for every bucket.** It is blocked for buckets with **Object Lock** enabled, and for buckets with **Versioning** enabled. Delete objects in those buckets with an S3-compatible client instead. ## Delete a bucket **Delete bucket** sits in the **Danger Zone** on the **General** tab. You can also delete an empty bucket from the bucket list. > **Warning** > > **Only empty buckets can be deleted.** If the bucket still contains objects, **Delete bucket** is disabled and the card reads *"This bucket contains X objects. Empty it first to delete."* — use [Empty bucket](#empty-a-bucket) first. Click **Delete bucket**, then confirm with **Delete**. *This action cannot be undone.* > **Note** > > **Buckets with Object Lock enabled can't be deleted — even when empty.** If you enabled Object Lock at creation, the bucket is permanent and cannot be deleted, regardless of whether it contains any objects. See [Objects → Locking](/docs/infrastructure/object-storage/objects/object-locking). ## Use the API Bucket operations in the public API: `GET /object-storage/buckets`, `POST /object-storage/buckets` (Object Lock and its default retention can be set here with `object_lock_enabled` and `default_retention`), `GET /object-storage/buckets/{bucket_name}`, `PATCH /object-storage/buckets/{bucket_name}` (`is_public` only), and `DELETE /object-storage/buckets/{bucket_name}` (scope `object-storage.delete`). Usage totals, metrics, the Public Access URL, Empty bucket, and the **Lifecycle Policies**, **CORS**, **Lock Settings**, **Event Notifications**, and **Custom Domains** tabs have no API operation; use the portal. ## Related * [Concepts](/docs/infrastructure/object-storage/core-concepts) * [Getting started](/docs/infrastructure/object-storage/upload-your-first-object) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Pricing](/docs/infrastructure/object-storage/pricing) --- title: Bucket Policies url: https://ibee.ai/docs/infrastructure/object-storage/buckets/bucket-policies description: Control bucket access in IBEE Object Storage — toggle public access, scope API credential permissions to specific buckets, and use bucket-level access controls. last_updated: 2026-09-28 --- # Bucket Policies > Control bucket access in IBEE Object Storage — toggle public access, scope API credential permissions to specific buckets, and use bucket-level access controls. Bucket access in IBEE Object Storage is controlled through two mechanisms: * **Public Access** — a bucket-level toggle that exposes objects unauthenticated via a Public Access URL. * **API Credentials** — programmatic access scoped to a permission level and a set of buckets. For browser-based cross-origin access, see [CORS](/docs/infrastructure/object-storage/buckets/cors). For Object Lock retention, see [Objects → Locking](/docs/infrastructure/object-storage/objects/object-locking). ## Public access Enabling **Public Access** allows objects in the bucket to be served unauthenticated via a **Public Access URL**. ### Open General settings Open your bucket → click **Settings** → click the **General** tab. ### Enable Public Access Toggle **Public Access** from Disabled to Enabled. A confirmation toast appears: *"Bucket access changed to public"*. ### Enable the Public Access URL The **Public Access URL** section becomes active but no URL is assigned automatically — it shows *"No Public Access URL is assigned to this bucket."* Click **Enable** in the top-right of the **Public Access URL** card to assign a URL to the bucket. Copy the URL. Objects are then accessible at: ``` https:/// ``` > **Note** > > The Public Access URL is **rate-limited and not recommended for production**. For production traffic, connect a [custom domain](/docs/infrastructure/object-storage/buckets/custom-domains) to the bucket. To turn the URL off, click **Disable** on the **Public Access URL** card. > **Warning** > > Enabling Public Access makes **all objects** in the bucket readable without authentication. Only enable this for buckets intended for public content. > **Info** > > If Public Access is disabled, the Public Access URL section shows: **"Please enable public access in General to use the Public Access URL."** To serve from your own hostname instead of the assigned Public Access URL, see [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) — the bucket must be public to register a custom domain. ## API Credential access For programmatic access via the AWS CLI, rclone, or any S3-compatible tool, use an **S3 credential**, created under **Organization → API Tokens → S3 Credentials**. Each credential belongs to one workspace and provides: * **Access Key ID** + **Secret Access Key** — for S3-compatible tools * **S3 Endpoint** — `https://{workspaceId}.blob.ibeestorage.com` ### Permission levels Each credential is created with one Object Storage permission level: | Permission | What it allows | | ----------------------- | --------------------------------------------------------------------------------------- | | **Admin Read & Write** | Create, list, delete buckets, edit bucket configuration, read, write, and list objects. | | **Admin Read only** | List buckets, view configuration, read and list objects. | | **Object Read & Write** | Read, write, and list objects in specific buckets. | | **Object Read only** | Read and list objects in specific buckets. | ### Bucket scoping **Admin** credentials always apply to every bucket in the credential's workspace. **Object Read & Write** and **Object Read only** credentials can apply to: * **All buckets in the selected workspace** — the simplest option for application-wide access. * **Specific buckets only** — pick one or more buckets the credential can access. This is the bucket-level access boundary: a credential scoped to bucket `A` cannot read or write to bucket `B`. [Create an API credential →](/docs/infrastructure/object-storage/api-tokens) ## Best practices * **Default to private.** Only enable Public Access on buckets that genuinely serve public content (websites, media, downloads). * **Use one credential per application or environment** with the narrowest permission level and bucket scope that works. * **Rotate credentials** by creating a new credential, switching applications to use it, then revoking the old one. The Secret Access Key is shown only once — store it securely. * **Separate buckets** for prod / staging / dev rather than relying on prefix-based separation alone. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [CORS](/docs/infrastructure/object-storage/buckets/cors) * [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) * [Objects → Locking](/docs/infrastructure/object-storage/objects/object-locking) --- title: Lifecycle Management url: https://ibee.ai/docs/infrastructure/object-storage/buckets/lifecycle-management description: Create lifecycle rules in IBEE Object Storage to automatically delete objects after a set number of days or on a date. last_updated: 2026-10-19 --- # Lifecycle Management > Create lifecycle rules in IBEE Object Storage to automatically delete objects after a set number of days or on a date. A **lifecycle rule** is attached to a bucket and runs against the objects inside it. Use rules to delete old data automatically, for example logs or temporary files under a prefix. ## Before you begin * An active IBEE Solutions organization with a bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) ### 1. Open Lifecycle Policies Open a bucket, click the **Settings** tab, then click the **Lifecycle Policies** tab. ### 2. Add a rule Click **Add Rule**. A bucket with no rules shows **No lifecycle rules** until you add one. ![IBEE Object Storage lifecycle policies](/docs/_fern-files/_img/431d498cfc0e96e5b07511cb0995f4e534c60defd53657dcfd4bca50b90476ef.webp)![IBEE Object Storage lifecycle policies](/docs/_fern-files/_img/5edd9199f5b605a169bc18480bcee7879919f263e876aab122939ddb74b63e60.webp) ### 3. Configure the rule Fill in the **Lifecycle rules** panel — subtitle: *"Automatically expire objects, clean incomplete uploads, or move data after a set period."* | Field | Type | Default | Description | | ------------------ | ------------------------------- | ------- | -------------------------------------------------------------------------------------- | | Prefix filter | Text | — | Placeholder `e.g. logs/`. Leave empty to apply this rule to all objects in the bucket. | | Rule status | Toggle | Enabled | Enable or disable the rule. Disabled rules remain saved but are not executed. | | Expire after | Checkbox + **Days** or **Date** | 30 days | Delete matching objects after a number of days, or on a specific date. | | Incomplete uploads | Checkbox + days | 7 days | Meant to abort unfinished multipart uploads after the number of days. Not applied yet. | | Transition after | Checkbox + **Days** or **Date** | 30 days | Meant to move objects to another storage class. Not applied yet. | Under **Lifecycle actions**, the helper text reads *"Select at least one action before applying changes."* Click **Apply changes**. > **Info** > > At least one lifecycle action must be selected before you can apply changes. > **Warning** > > Only **Expire after** is applied to objects today. **Incomplete uploads** and **Transition after** can be set in the form, but the storage service does not apply them yet, and the form has no storage-class choice for a transition. ## Manage rules Each rule is listed as a card with a summary of its actions. * **Edit** — click the rule to expand it, change the fields, and click **Apply changes**. * **Enable or disable** — use the toggle on the card. A disabled rule stays saved but does not run. * **Delete** — click the delete icon on the card, then **Delete** in the **Delete lifecycle rule** dialog. ## Troubleshooting **Apply changes is disabled** At least one lifecycle action (Expire after, Incomplete uploads, or Transition after) must be checked before applying changes. **Rule is not executing** Check that the **Rule status** toggle is set to **Enabled**. Disabled rules are saved but not executed. **Rule applying to all objects unexpectedly** If the **Prefix filter** field is empty, the rule applies to all objects in the bucket. Add a prefix to restrict scope. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [Pricing](/docs/infrastructure/object-storage/pricing) --- title: CORS url: https://ibee.ai/docs/infrastructure/object-storage/buckets/cors description: Configure CORS rules on an IBEE Object Storage bucket to allow browser applications to access your files. Set allowed origins, HTTP methods, and headers. last_updated: 2026-10-19 --- # CORS > Configure CORS rules on an IBEE Object Storage bucket to allow browser applications to access your files. Set allowed origins, HTTP methods, and headers. CORS (Cross-Origin Resource Sharing) lets browser applications access files in your bucket from a different domain. Add CORS rules to specify which origins, HTTP methods, and headers are permitted. ## Before you begin * An active IBEE Solutions organization with a bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) > **Info** > > **About CORS** > > * CORS allows browser applications to access your bucket files. > * Add your domain to allowed origins (e.g., `https://myapp.com`). > * Use wildcards for subdomains (e.g., `*.myapp.com`). > **Warning** > > **Changes may take up to 5 minutes to propagate.** > CORS configuration is cached. Wait at least 5 minutes after saving before testing. ### 1. Go to CORS settings Open a bucket, click the **Settings** tab, then click **CORS** in the settings sub-navigation. ### 2. Add a rule Click **Add Rule** on the **CORS Policy** card. A bucket with no rules shows **No CORS rules** until you add one. ### 3. Configure the rule Fill in the **Add CORS Rule** dialog — subtitle: *"Configure cross-origin resource sharing for browser access."* **Allowed Origins** Helper: *"Specify which domains can access this bucket from a browser:"* Enter an origin in the input (placeholder: `https://myapp.com or *.myapp.com`) and click **+ Add Origin** to add more. Use `*` to allow all origins. **Allowed Methods** Helper: *"Select which HTTP methods are allowed:"* | Method | Default | | ------ | --------- | | GET | ✅ Enabled | | PUT | — | | POST | — | | DELETE | — | | HEAD | — | **Allowed Headers** Helper: *"Comma-separated list of headers browsers can send:"* — defaults to `*` (allow all headers). ### 4. Save the rule Click **Save Rule** to apply. Click **Cancel** to discard. ## Verify Your new rule appears in the **CORS Policy** list with its origins and methods. Allow up to 5 minutes for the configuration to propagate before testing from a browser. ## Edit or delete a rule Each rule in the **CORS Policy** list has **Edit** and **Delete**. **Edit** opens the **Edit CORS Rule** dialog; click **Save Rule** to apply. **Delete** asks you to confirm in the **Delete CORS rule** dialog. ## Troubleshooting **CORS rule not taking effect** CORS configuration is cached. Wait at least 5 minutes after saving before testing. **Browser still blocked after adding origin** Ensure the origin exactly matches the request origin — including the protocol (`https://`) and no trailing slash. **Rule with a wildcard origin won't save** If saving fails for a pattern such as `*.myapp.com`, add each full origin instead (for example `https://app.myapp.com`), or use `*` to allow all origins. **All requests blocked** Ensure the HTTP method used by your browser app (e.g. `PUT` for uploads) is checked in **Allowed Methods**. **Allowed Headers errors** If your app sends custom headers, add them explicitly or use `*` to allow all headers. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [Lifecycle](/docs/infrastructure/object-storage/buckets/lifecycle-management) * [Presigned URLs](/docs/infrastructure/object-storage/objects/presigned-urls) --- title: Custom Domains url: https://ibee.ai/docs/infrastructure/object-storage/buckets/custom-domains description: Serve IBEE Object Storage bucket content from your own domain by adding a CNAME record and verifying your hostname in the bucket settings. last_updated: 2026-09-28 --- # Custom Domains > Serve IBEE Object Storage bucket content from your own domain by adding a CNAME record and verifying your hostname in the bucket settings. Custom domains let you serve bucket content from your own hostname (e.g. `cdn.example.com`) instead of the default IBEE Public Access URL. You add a CNAME record in your DNS provider, then register the domain in the bucket settings. ## Before you begin * An active IBEE Solutions organization with a verified account * A bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) * **Public Access enabled on the bucket** — see [Bucket policies → Public access](/docs/infrastructure/object-storage/buckets/bucket-policies#public-access) * Access to your domain's DNS settings > **Warning** > > **The bucket must be public to configure a custom domain.** If Public Access is disabled, the Custom Domains tab shows the error *"Bucket must be public to configure custom domain"* and the CNAME target shown under Step 1 will be `Unavailable`. > **Info** > > **Custom domains are a billable add-on.** When you click **Add Domain**, the portal first checks your organization's billing status. If your wallet balance or credit limit can't cover the add-on, a billing message appears instead of the **Add Custom Domain** dialog — add credits and try again. ## Add a custom domain ### Open bucket settings Open your bucket in the portal, click the **Settings** tab, then click **Custom Domains**. ### Add a domain Click **+ Add Domain**. The **Add Custom Domain** modal appears with the subtitle *"Connect your bucket to a custom domain."* ### Add the CNAME record (Step 1) The modal's **Step 1** shows the field *"Add a CNAME record in your DNS pointing to:"* with the CNAME target. Click **Copy** to copy the target: ``` {hash}.ibee.zone ``` Go to your DNS provider and add a CNAME record: | Type | Host | Value | | ----- | ------------------------- | --------------------------------------- | | CNAME | `cdn` (or your subdomain) | `{hash}.ibee.zone` (copied from portal) | > **Info** > > DNS propagation can take some time before verification succeeds. Wait for propagation to complete before proceeding to Step 2. ### Enter your domain (Step 2) After adding the CNAME record, enter your full domain in the **Step 2** field — *"Enter your domain after the CNAME record is added."* Placeholder: `cdn.example.com`. ``` cdn.example.com ``` ### Save Click **Add Domain**. The domain appears in the **Custom Domains** list with a status: | Status | Meaning | | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | **Pending DNS Verification** | Waiting for the CNAME record to resolve to the target. | | **Provisioning SSL** | DNS is verified; the HTTPS certificate is being issued. | | **Active** | The domain is serving bucket content over HTTPS. | | **Error** | Setup failed. Check the CNAME record; if the status doesn't recover, remove the domain and add it again. | To stop serving from a domain, click **Remove** next to it in the list and confirm. ## Troubleshooting **Verification fails immediately after adding the domain** DNS propagation takes time. Wait a few minutes after adding the CNAME record, then try again. **CNAME record not resolving** Verify the CNAME record is saved correctly in your DNS provider. The record value must exactly match the target shown in the portal. **Domain stays in Pending DNS Verification** Ensure the CNAME points to the full target including `.ibee.zone`. Some DNS providers strip the trailing dot — confirm the value is saved as shown. **CNAME target shows `Unavailable`** The bucket is not public. Enable Public Access first — see [Bucket policies → Public access](/docs/infrastructure/object-storage/buckets/bucket-policies#public-access). ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [CDN integration](/docs/infrastructure/object-storage/cdn-integration) * [Static Site Hosting](/docs/infrastructure/object-storage/static-site-hosting) --- title: Event Notifications url: https://ibee.ai/docs/infrastructure/object-storage/buckets/event-notifications description: Configure webhook notifications on an IBEE Object Storage bucket to receive POST requests when objects are uploaded. Filter by prefix or suffix to target specific files. last_updated: 2026-10-19 --- # Event Notifications > Configure webhook notifications on an IBEE Object Storage bucket to receive POST requests when objects are uploaded. Filter by prefix or suffix to target specific files. Event notifications send a POST request to your webhook URL when objects are uploaded to a bucket. Use prefix and suffix filters to target specific paths or file types. ## Before you begin * An active IBEE Solutions organization with a verified account * A bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) * A publicly accessible HTTPS endpoint to receive webhook POST requests ## Add a webhook notification ### Open bucket settings Open your bucket in the portal, click the **Settings** tab, then click **Event Notifications**. ### Add a notification Click **Add Notification** on the **Webhook Notifications** card. The **Add Notification** modal appears with the subtitle *"Configure webhook endpoint and event types."* ### Configure the webhook **Webhook URL** (required) Helper: *"The URL that will receive POST requests when events occur."* Placeholder: `https://your-app.com/`. ``` https://your-app.com/webhook ``` **Event Types** (required) Helper: *"Select which events should trigger notifications:"* | Event | Description | | ---------------------------- | ----------------------------------- | | **Creation of a new object** | Triggered when objects are uploaded | | **Deletion of an object** | Triggered when objects are deleted | At least one event type must be selected. > **Warning** > > Deletion events are not delivered at the moment, and a notification with only **Deletion of an object** selected fails to save. Select **Creation of a new object** for a working notification. ### Set filters (optional) Expand **Advanced Options** — *"Filter notifications to specific objects based on prefix or suffix:"* | Filter | Placeholder | Helper | | ---------- | ---------------- | ------------------------------------------------- | | **Prefix** | `e.g., uploads/` | Only trigger for objects with this path prefix | | **Suffix** | `e.g., .jpg` | Only trigger for objects with this file extension | Leave both empty to receive notifications for all objects in the bucket. ### Save Click **Save Notification**. The webhook appears in the **Webhook Notifications** list. ## Edit or delete a notification Each webhook in the **Webhook Notifications** list has **Edit** and **Delete**. **Edit** opens the **Edit Notification** modal; click **Save Notification** to apply. **Delete** shows a *Delete this notification?* prompt; click **Delete** in it to remove the webhook. ## Troubleshooting **Webhook not receiving events** Ensure the webhook URL is publicly accessible over HTTPS. IBEE sends POST requests — verify your endpoint is not blocking them. **Too many notifications** Use the **Prefix** or **Suffix** filters under Advanced Options to limit notifications to specific paths or file types. **Notifications for wrong event type** Check that the correct event types (**Creation** and/or **Deletion**) are selected for the notification. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Objects](/docs/infrastructure/object-storage/objects) * [Lifecycle](/docs/infrastructure/object-storage/buckets/lifecycle-management) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) --- title: Objects url: https://ibee.ai/docs/infrastructure/object-storage/objects description: Upload, download, list, and delete objects in IBEE Object Storage buckets — from the portal or any S3-compatible client. last_updated: 2026-10-19 --- # Objects > Upload, download, list, and delete objects in IBEE Object Storage buckets — from the portal or any S3-compatible client. An **object** is a single file plus its metadata, stored in a bucket. Each object is identified by its **key** — the path-like name within the bucket. ## What you can do with objects #### [Object Locking](/docs/infrastructure/object-storage/objects/object-locking) Mark objects immutable for compliance or ransomware protection. #### [Presigned URLs](/docs/infrastructure/object-storage/objects/presigned-urls) Generate time-limited URLs for upload or download — no shared credentials. ## Object basics | Property | Detail | | ----------------- | --------------------------------------------------------------------------------- | | **Key** | The object's name within the bucket. Up to 1,024 bytes, UTF-8. | | **Size** | Up to 5 TiB per object. See [Limits](/docs/infrastructure/object-storage/limits). | | **Type** | MIME type set on upload (e.g. `image/jpeg`, `application/pdf`). | | **Storage class** | `Standard`. | | **Metadata** | System metadata (size, last-modified, ETag) plus optional custom headers. | ## Upload from the portal You can upload, download, and delete objects directly from the IBEE Solutions portal. ### 1. Open a bucket Go to `portal.ibee.ai/organizations/{orgId}/workspaces/{workspaceId}/object-storage` and click a bucket name from the list. ### 2. Upload The **Objects** tab has two action buttons in the top right: **Create Folder** and **Upload**. Click **Upload** to pick files, or open the arrow next to it and choose **Upload files** or **Upload folder**. You can also drag and drop files onto the objects list. ![IBEE Object Storage upload interface](/docs/_fern-files/_img/26cf7d39d6bbb119085e427e20a67871cb3c0951093817daa1e14b51f48a409b.webp)![IBEE Object Storage upload interface](/docs/_fern-files/_img/7ac84a1635f5813b67cd1c7a00161eebbe52055aa7eb989bcd852657e370341a.webp) An empty bucket or folder shows **Upload Files** and **Upload Folder** buttons instead. Uploads run in an upload panel that shows each file's progress; you can cancel a running upload there. > **Info** > > The portal accepts files up to **300 MB** each. Larger files are rejected with *"Files larger than 300 MB must be uploaded via the API"* — upload them with an [S3-compatible client](#upload-from-an-s3-compatible-client) instead. ### 3. Confirm Uploaded files appear in the objects list with their **Type**, **Storage Class**, **Size**, and **Modified** date. ## Object list columns | Column | Description | | ------------- | ---------------------------------------------------------------------------------- | | OBJECTS | Object or folder name | | TYPE | MIME type (e.g. `image/jpeg`, `image/png`, `application/octet-stream`) or `Folder` | | STORAGE CLASS | Storage class (e.g. `Standard`) | | SIZE | Object size — shown as `–` for folders | | MODIFIED | Last modified date and time | | ACTIONS | Download + delete for objects; open link + delete for folders | ## Create a folder Click **Create Folder**, enter a **Folder Name** (letters, numbers, hyphens, and underscores; placeholder `my-folder`), and click **Create Folder**. The folder is created inside the folder you have open. ## Download Click the **download icon** next to the object in the list. Or click the object name to open its detail page and click **Download** in the top right. ## Delete Click the **delete icon** next to the object in the list. Or open the detail page and click **Delete**. To delete several files at once, tick their checkboxes and click **Delete** in the toolbar (it shows how many are selected), then confirm. **Clear selection** cancels the selection. > **Warning** > > A bucket must be empty before it can be deleted. To remove everything at once, use [Empty bucket](/docs/infrastructure/object-storage/buckets#empty-a-bucket), then [delete the bucket](/docs/infrastructure/object-storage/buckets#delete-a-bucket). ## Object detail page Click an object name to open its detail page at `portal.ibee.ai/organizations/{orgId}/workspaces/{workspaceId}/object-storage/{bucket}/{object_name}`. The **Object Details** card shows: | Field | Description | | -------- | ------------------------------------------- | | Name | Object name | | Size | Object size | | Type | MIME type of the object (e.g. `image/jpeg`) | | Modified | Last modified date and time | | Access | `Public` (with green dot) or `Private` | For objects in a public bucket with a Public Access URL, the page also shows the object's **Public Development URL** with a copy button. That URL is rate-limited and not meant for production — see [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies#public-access). Image files are previewed inline under the **Object Preview** section. Available actions in the top-right: **Download**, **Delete**. ## Upload from an S3-compatible client Use the organization's S3 endpoint and an [API credential](/docs/infrastructure/object-storage/api-tokens) with **Object Read & Write** or **Admin Read & Write** scope. ```bash # Single file aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ s3 cp report.pdf s3://my-bucket/reports/2026-05.pdf # Whole directory aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ s3 sync ./build/ s3://my-bucket/site/ # List aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ s3 ls s3://my-bucket/reports/ # Delete aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ s3 rm s3://my-bucket/reports/2026-05.pdf ``` Files larger than 100 MB are automatically uploaded as multipart by the AWS CLI and SDK. See [Limits](/docs/infrastructure/object-storage/limits) for size and rate caps. ## Folder structure Object Storage has no real folder hierarchy — only keys with `/` separators. The portal renders prefixes as folders. Use prefixes for logical grouping (e.g. `logs/2026/05/`, `users/123/avatar.png`) and pair with [Lifecycle rules](/docs/infrastructure/object-storage/buckets/lifecycle-management) scoped by prefix to manage retention per "folder". ## Troubleshooting **Upload button not visible** Ensure you are on the **Objects** tab inside a bucket, not on the main Object Storage list page. **File not appearing after upload** Refresh the page. If the file still does not appear, try uploading again. **Cannot delete bucket** The bucket still contains objects. Run [Empty bucket](/docs/infrastructure/object-storage/buckets#empty-a-bucket) first. Buckets with Object Lock enabled can't be emptied or deleted. **Upload rejected: "Files larger than 300 MB must be uploaded via the API"** The portal upload limit is 300 MB per file. Use an [S3-compatible client](#upload-from-an-s3-compatible-client) for larger files. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Locking](/docs/infrastructure/object-storage/objects/object-locking) * [Presigned URLs](/docs/infrastructure/object-storage/objects/presigned-urls) * [Mount as filesystem](/docs/infrastructure/object-storage/mount-a-bucket-as-a-filesystem) --- title: Object Locking url: https://ibee.ai/docs/infrastructure/object-storage/objects/object-locking description: Mark objects as immutable for compliance, ransomware protection, or regulatory holds. Object Lock is a permanent bucket setting in IBEE Object Storage. last_updated: 2026-10-19 --- # Object Locking > Mark objects as immutable for compliance, ransomware protection, or regulatory holds. Object Lock is a permanent bucket setting in IBEE Object Storage. **Object Lock** prevents objects from being deleted or overwritten while a retention period is in effect. Use it for compliance (financial records, audit logs), ransomware protection, or any case where data integrity must be guaranteed. > **Warning** > > **Object Lock is a permanent bucket setting.** It must be enabled at **bucket creation time** in the **Versioning and object lock** section of the create-bucket page. It cannot be enabled, disabled, or changed after the bucket is created. ## Enable Object Lock at bucket creation When creating a bucket, turn on **Object lock (WORM)** in the **Versioning and object lock** section before clicking **Create Bucket**. Turning it on also turns on **Versioning**. See [Buckets → Create a bucket](/docs/infrastructure/object-storage/buckets#create-a-bucket). You can set the bucket's default retention right there: pick **None**, **Governance**, or **Compliance** and, for Governance or Compliance, a **Retention period** in days (default 30). After creation, the **Lock Settings** tab is active for the bucket and you can change the default retention at any time. ## Lock Settings tab After bucket creation, find the lock state in two places: * The **General** tab shows **Object Lock** as a read-only field (Enabled or Disabled). * The **Lock Settings** tab shows the active retention configuration. ### If Object Lock was enabled at creation The **Lock Settings** tab lets you manage retention policies for objects in the bucket. Object Lock applies to objects uploaded **after** retention is configured. ### If Object Lock was not enabled at creation The **Lock Settings** tab shows the message: > **Object Lock not enabled** — *"Object locking must be enabled when creating the bucket to use retention policies. This setting cannot be changed after bucket creation."* To use Object Lock for that workload, create a new bucket with the option turned on and migrate objects. ## How retention works A locked object cannot be overwritten or deleted until its **retention period** expires. You configure retention on the **Lock Settings** tab under **Default Retention Policy**, which applies to every object uploaded **after** the policy is saved. A policy has two parts: a **retention mode** and a **retention period**. ### Retention modes The retention mode controls *who* can shorten or remove the lock before it expires. Choose one: | Mode | Who can override | Use it for | | -------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | **GOVERNANCE** | Users with special permissions can override retention and delete or modify objects early. | Internal data-integrity policies where a privileged operator may still need an escape hatch. | | **COMPLIANCE** | No one can delete or modify objects until retention expires — not even an Admin token. | Regulatory holds, financial records, and audit logs where immutability must be guaranteed. | > **Warning** > > **COMPLIANCE is the strictest protection.** Once an object is written under a COMPLIANCE retention period, neither you nor any token can delete or overwrite it until the period expires. Confirm the retention period is correct before you save. ### Retention period The retention period is *how long* objects stay locked. Set it under **Retention Period** using a number plus a unit (**Days** or **Years**); the page shows the resolved **Total Retention Period** below the field. The lock stays in effect for that duration from the time each object is uploaded. ### Set a default retention policy 1. Open the bucket and go to the **Lock Settings** tab. 2. Under **Default Retention Policy**, click **Edit**. 3. Select a **Retention Mode** — **GOVERNANCE** or **COMPLIANCE**. 4. Set the **Retention Period** value and unit (**Days** or **Years**), and check the **Total Retention Period** summary. 5. Click **Save Changes**. The policy status shows as **Configured** and applies to objects uploaded afterward. Use Object Lock together with API token scoping ([Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies)) so that no path can bypass the lock. ## Lock individual objects In a bucket with Object Lock enabled, each object's actions menu on the **Objects** tab has two extra entries. ### Set retention on one object 1. Open the object's actions menu and click **Set Retention**. 2. Choose a **Retention Mode** — **Governance (Admin can override)** or **Compliance (Cannot delete by anyone)**. 3. Enter **Retain for (days)**. The dialog shows the resulting **Locked until** date. 4. Click **Lock File**. Once an object has retention, the menu shows its locked-until date instead of **Set Retention**. ### Legal hold A legal hold locks an object with no expiry date, independently of retention. While legal hold is on, the object cannot be deleted or modified, and the hold stays until someone removes it. * To place a hold, open the object's actions menu and click **Set Legal Hold**, turn the hold **ON**, and click **Apply ON**. * To lift it, click **Remove Legal Hold**. Objects under legal hold can't be deleted from the portal — the delete button shows *"Cannot delete: object has legal hold"*. ## Best practices * **Decide at creation time.** Because Object Lock cannot be added later, plan before creating buckets that may need immutability. * **Pair with lifecycle rules carefully.** Lifecycle expiry cannot delete locked objects; verify rules don't silently fail on protected data. * **Document your retention policy** internally so future engineers understand why objects can't be deleted. * **Don't lock everything.** Reserve Object Lock for buckets where immutability is genuinely required. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [Lifecycle](/docs/infrastructure/object-storage/buckets/lifecycle-management) * [Concepts](/docs/infrastructure/object-storage/core-concepts) --- title: Presigned URLs url: https://ibee.ai/docs/infrastructure/object-storage/objects/presigned-urls description: Generate time-limited URLs for uploading or downloading IBEE Object Storage objects without sharing your credentials. last_updated: 2026-09-28 --- # Presigned URLs > Generate time-limited URLs for uploading or downloading IBEE Object Storage objects without sharing your credentials. A **presigned URL** is a regular HTTPS URL with an embedded signature that grants temporary access to a single object — no Access Key required by the recipient. Use presigned URLs to: * Let a user **download** a private object from a browser, without giving them credentials. * Let a client **upload** a file directly to your bucket, bypassing your backend. * Hand a third-party system temporary access to a single file. The URL stops working when its expiry passes. ## Before you begin * A bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) * An [API credential](/docs/infrastructure/object-storage/api-tokens) with at least **Object Read & Write** scope on the target bucket — used to sign URLs The S3 endpoint for the bucket's workspace is `https://{workspaceId}.blob.ibeestorage.com`. ## Generate a download URL with the AWS CLI ```bash aws --endpoint-url https://{workspaceId}.blob.ibeestorage.com \ --profile ibee \ s3 presign s3://my-bucket/reports/2026-05.pdf \ --expires-in 3600 ``` The command prints a URL with embedded signature parameters: ```text https://{workspaceId}.blob.ibeestorage.com/my-bucket/reports/2026-05.pdf? X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=... &X-Amz-Date=... &X-Amz-Expires=3600 &X-Amz-SignedHeaders=host &X-Amz-Signature=... ``` Anyone with the URL can `GET` the object until the expiry passes. ## Generate from an SDK **`Python (boto3)`** ```python title="Python (boto3)" from datetime import timedelta import boto3 s3 = boto3.client( "s3", endpoint_url="https://{workspaceId}.blob.ibeestorage.com", aws_access_key_id="AKIA...", aws_secret_access_key="", ) url = s3.generate_presigned_url( "get_object", Params={"Bucket": "my-bucket", "Key": "reports/2026-05.pdf"}, ExpiresIn=int(timedelta(hours=1).total_seconds()), ) print(url) ``` **`Node.js (AWS SDK v3)`** ```javascript title="Node.js (AWS SDK v3)" import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"; import { getSignedUrl } from "@aws-sdk/s3-request-presigner"; const s3 = new S3Client({ endpoint: "https://{workspaceId}.blob.ibeestorage.com", credentials: { accessKeyId, secretAccessKey }, }); const url = await getSignedUrl( s3, new GetObjectCommand({ Bucket: "my-bucket", Key: "reports/2026-05.pdf" }), { expiresIn: 3600 } ); console.log(url); ``` ## Presigned uploads (`PUT`) Generate a URL the client can `PUT` to directly: ```python url = s3.generate_presigned_url( "put_object", Params={ "Bucket": "my-bucket", "Key": "uploads/avatar.png", "ContentType": "image/png", }, ExpiresIn=600, ) ``` The client uploads with a single HTTP request: ```bash curl -X PUT "$URL" \ -H "Content-Type: image/png" \ --data-binary @avatar.png ``` ## Presigned `POST` (browser uploads with form data) `POST` policies are the right fit for browser-based form uploads — they let you constrain the upload (key prefix, max size, content type) before the file is sent. ```python post = s3.generate_presigned_post( Bucket="my-bucket", Key="uploads/${filename}", Conditions=[ ["content-length-range", 0, 10 * 1024 * 1024], # 10 MB max ["starts-with", "$Content-Type", "image/"], ], ExpiresIn=600, ) print(post) # url + fields ``` ## Best practices * **Use the shortest expiry that works.** Don't issue a long-lived URL when 5 minutes is enough. * **Bind to content type and size** for upload URLs to prevent abuse. * **Don't log presigned URLs** — anyone who reads the log gets the same access. * **Treat them as one-time secrets** — regenerate per request rather than caching. ## Limitations * The URL stops working if the API token used to sign it is revoked. * Each presigned URL is valid for **one HTTP method on one key**. Different operations need different URLs. ## Related * [Objects](/docs/infrastructure/object-storage/objects) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [CORS](/docs/infrastructure/object-storage/buckets/cors) --- title: Mount a Bucket as a Filesystem url: https://ibee.ai/docs/infrastructure/object-storage/mount-a-bucket-as-a-filesystem description: Access an IBEE Object Storage bucket as a local directory using s3fs or rclone, so tools that expect POSIX paths can read and write objects. last_updated: 2026-09-28 --- # Mount a Bucket as a Filesystem > Access an IBEE Object Storage bucket as a local directory using s3fs or rclone, so tools that expect POSIX paths can read and write objects. A bucket can be mounted as a local filesystem, letting tools that expect POSIX paths read and write objects without any code changes. This is useful for migrations, backup tools, build pipelines, or any utility that doesn't speak S3 natively. > **Info** > > Object Storage isn't a real POSIX filesystem. Mounted access works well for sequential reads, batch writes, and general file workflows — but avoid it for random small writes or anything that depends on file locking. ## Before you begin * A bucket ([Create a bucket](/docs/infrastructure/object-storage/buckets)) * An [API credential](/docs/infrastructure/object-storage/api-tokens) with at least **Object Read & Write** scope on the target bucket * The S3 endpoint for the bucket's workspace: `https://{workspaceId}.blob.ibeestorage.com` (shown as **S3 Endpoint** when you create the credential) ## Pick a tool | Tool | Best for | Notes | | ---------- | ---------------------------------------------- | --------------------------------- | | **s3fs** | Linux / macOS — quick mount of a single bucket | Simple, FUSE-based | | **rclone** | Cross-platform, large transfers, scripting | Has both `mount` and `sync` modes | ## s3fs (Linux / macOS) Install: ```bash # Ubuntu / Debian sudo apt-get install s3fs # macOS brew install s3fs ``` Save your credentials: ```bash echo "AKIA...:" > ~/.passwd-s3fs chmod 600 ~/.passwd-s3fs ``` Mount the bucket: ```bash mkdir -p /mnt/my-bucket s3fs my-bucket /mnt/my-bucket \ -o url=https://{workspaceId}.blob.ibeestorage.com \ -o use_path_request_style \ -o passwd_file=~/.passwd-s3fs ``` Now `/mnt/my-bucket` reads and writes against the bucket. Unmount: ```bash fusermount -u /mnt/my-bucket # Linux umount /mnt/my-bucket # macOS ``` ### Auto-mount at boot (Linux) Add to `/etc/fstab`: ```text my-bucket /mnt/my-bucket fuse.s3fs _netdev,allow_other,url=https://{workspaceId}.blob.ibeestorage.com,use_path_request_style,passwd_file=/root/.passwd-s3fs 0 0 ``` ## rclone Install: [rclone.org/install](https://rclone.org/install/) Configure a remote: ```bash rclone config # n) New remote # name> ibee # Storage> s3 # provider> Other # access_key_id> AKIA... # secret_access_key> # endpoint> https://{workspaceId}.blob.ibeestorage.com ``` Mount: ```bash mkdir -p /mnt/my-bucket rclone mount ibee:my-bucket /mnt/my-bucket --vfs-cache-mode writes ``` Or sync without mounting: ```bash rclone sync ./local-dir ibee:my-bucket/remote-dir ``` ## Performance notes * **Sequential is fast, random is slow.** Mounted filesystems shine for whole-file reads and writes; small in-place edits trigger full re-uploads. * **Cache aggressively.** Tools like `rclone` and `s3fs` have local cache options — use them. * **Don't use as a database backing store.** No file locking, no atomic appends. ## Common pitfalls * **Symlinks** are not real symlinks — they become regular files containing the link path. * **File modification time** comes from object metadata; tools that rely on `mtime` may behave unexpectedly. * **`du` is slow** because it has to list every object. ## Related * [Buckets](/docs/infrastructure/object-storage/buckets) * [Objects](/docs/infrastructure/object-storage/objects) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Concepts](/docs/infrastructure/object-storage/core-concepts) --- title: Metrics url: https://ibee.ai/docs/infrastructure/object-storage/metrics description: Monitor bucket usage, object counts, storage operations, and bandwidth from the IBEE Solutions portal — both at the organization level and per bucket. last_updated: 2026-10-19 --- # Metrics > Monitor bucket usage, object counts, storage operations, and bandwidth from the IBEE Solutions portal — both at the organization level and per bucket. Object Storage surfaces usage metrics at two levels — at the organization level on the main Object Storage page, and per bucket on the bucket's **Metrics** tab. ## Organization-level metrics Open **Object Storage** in the portal sidebar. The usage panel at the top of the page shows totals across all buckets in the organization: | Metric | Description | | -------------------- | --------------------------------------------- | | **Buckets** | Total number of buckets in the organization | | **Objects** | Total objects stored across all buckets | | **Storage Used** | Total storage consumed (B / MB / GB) | | **Bandwidth Egress** | Outbound data transfer for the billing period | The bucket list below shows the per-bucket breakdown: | Column | Description | | ------- | --------------------------------- | | BUCKET | Bucket name | | SIZE | Total storage used by that bucket | | CREATED | Creation date | ## Per-bucket metrics Open a bucket and click the **Metrics** tab. Choose **Last 24 hours** or **Last 7 days**. The tab shows when the data was last complete (*Data through …*) and these totals: | Card | Description | | --------------------------------------------- | ------------------------------------ | | **Current Storage** | Storage used by the bucket | | **Object Count** | Objects in the bucket | | **Data Retrieved from Origin** | Bytes read from the bucket | | **Class A Operations** | PUT, POST, LIST, and DELETE requests | | **Class B Operations** | GET and HEAD requests | | **Total Operations** | All requests | | **Successful Requests** / **Failed Requests** | Request outcomes | Below the cards, charts show **Data Retrieved from Origin**, **Operations** (total, Class A, Class B), and **Request outcomes** (successful and failed) over the selected range. Bucket metrics have no public API operation. The General tab also shows two read-only fields: | Field | Description | | ------------- | -------------------------------- | | Total Objects | Object count for the bucket | | Storage Used | Total storage used by the bucket | ## What to watch * **Sudden growth in Storage Used** — typically an upload bug, a runaway log job, or versioning without lifecycle. Pair the bucket with a [Lifecycle rule](/docs/infrastructure/object-storage/buckets/lifecycle-management). * **Bandwidth Egress exceeding plan** — front the bucket with the [CDN](/docs/infrastructure/object-storage/cdn-integration) for cacheable content, or check whether a public bucket is being scraped. * **Object count growing faster than data size** — a process is creating many small objects; consider batching or compressing. * **High Class A operation counts** — frequent write operations can indicate a misconfigured upload pipeline. Review application logic for unnecessary PUT/DELETE cycles. ## Related * [Pricing](/docs/infrastructure/object-storage/pricing) * [Limits](/docs/infrastructure/object-storage/limits) * [Lifecycle](/docs/infrastructure/object-storage/buckets/lifecycle-management) * [CDN integration](/docs/infrastructure/object-storage/cdn-integration) --- title: API Credentials url: https://ibee.ai/docs/infrastructure/object-storage/api-tokens description: S3 credentials for IBEE Object Storage. Create credentials from the API Tokens page to access buckets via AWS CLI, rclone, and S3-compatible tools. last_updated: 2026-10-19 --- # API Credentials > S3 credentials for IBEE Object Storage. Create credentials from the API Tokens page to access buckets via AWS CLI, rclone, and S3-compatible tools. S3 credentials let you access IBEE Object Storage buckets using any S3-compatible tool. Each credential is scoped to a **specific workspace** and provides an Access Key ID + Secret Access Key. Create credentials in the portal sidebar under **Organization → API Tokens**. Open the **S3 Credentials** tab and click **Create S3 Credential** (the **S3 API Credentials** button on the Object Storage page opens the same tab). Enter a name, choose the workspace and a permission level, and for object-level permissions choose the buckets, then click **Create Credential**. For permission levels and bucket scoping, see [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies#permission-levels) and [API Tokens](/docs/tools/api-tokens). > **Warning** > > The Secret Access Key is shown once only. Copy it immediately. If you lose it, revoke the credential and create a new one. ## S3 endpoint format ``` https://WORKSPACE-ID.blob.ibeestorage.com ``` Replace `WORKSPACE-ID` with your workspace identifier. The full endpoint is shown as **S3 Endpoint** when you create the credential. ## Manage S3 credentials The **S3 Credentials** tab lists credentials from every workspace you can access. Use the workspace filter to show one workspace. Each row shows **Access** (the workspace), **Permissions**, **Created**, **Last Used**, and **Status** (**Active** or **Revoked**). * **Revoke** an active credential to stop it working. The record stays in the list as **Revoked**. Applications using it may stop working, and this can't be undone. * **Delete** a revoked credential to remove it from the list. Click **Delete permanently** to confirm. To rotate a credential, create a new one, move your applications to it, then revoke the old one. In the public API, credentials are per workspace: `GET /object-storage/credentials`, `POST /object-storage/credentials` (`name`, `permission_type`, `bucket_scope`, `allowed_buckets`), `GET /object-storage/credentials/{access_key_id}`, and `DELETE /object-storage/credentials/{access_key_id}` to stop a credential working. ## Quick reference ### AWS CLI ```bash aws configure set aws_access_key_id YOUR-ACCESS-KEY-ID aws configure set aws_secret_access_key YOUR-SECRET-ACCESS-KEY aws configure set default.region us-east-1 # List buckets aws s3 ls --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com ``` ### rclone ```ini [ibee] type = s3 provider = Other access_key_id = YOUR-ACCESS-KEY-ID secret_access_key = YOUR-SECRET-ACCESS-KEY endpoint = https://WORKSPACE-ID.blob.ibeestorage.com ``` ## Related pages * [API Tokens](/docs/tools/api-tokens) — platform API tokens, token management, and revocation * [Create a bucket](/docs/infrastructure/object-storage/buckets) * [Permissions and policies](/docs/infrastructure/object-storage/buckets/bucket-policies) * [Upload and download objects](/docs/infrastructure/object-storage/objects) --- title: Hosting Static Sites and SPAs on Object Storage url: https://ibee.ai/docs/infrastructure/object-storage/static-site-hosting description: Complete guide to hosting static websites and single-page applications (React, Vue, Angular) on IBEE Object Storage with CDN, custom domains, and HTTPS. last_updated: 2026-10-27 --- # Hosting Static Sites and SPAs on Object Storage > Complete guide to hosting static websites and single-page applications (React, Vue, Angular) on IBEE Object Storage with CDN, custom domains, and HTTPS. IBEE Object Storage can serve static websites and single-page applications (SPAs) directly from a bucket. Combined with the CDN and a custom domain, you get global delivery, automatic HTTPS, and zero-server hosting for frontends built with React, Vue, Angular, Svelte, or plain HTML. ## Before you begin * An active IBEE Solutions organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)) * A built static site or SPA (output folder containing `index.html`) * An S3 credential for the bucket's workspace ([API Credentials](/docs/infrastructure/object-storage/api-tokens)) * AWS CLI or any S3-compatible tool installed locally ### 1. Build your site Generate the production build for your framework. The output folder is what you'll upload. | Framework | Build command | Output folder | | ----------------------- | ------------------------------------- | ------------------ | | React (CRA) | `npm run build` | `build/` | | React (Vite) | `npm run build` | `dist/` | | Next.js (static export) | `next build && next export` | `out/` | | Vue | `npm run build` | `dist/` | | Angular | `ng build --configuration production` | `dist//` | | Svelte / SvelteKit | `npm run build` | `build/` | | Plain HTML | — | your source folder | ### 2. Create a bucket [Create a bucket](/docs/infrastructure/object-storage/buckets#create-a-bucket). Keep **Automatic location**, or click **Need a specific location? click here** to pick one of the available sites. New buckets are private. After creating it, open the bucket → **Settings** → **General** and turn on **Public Access** ([Bucket policies → Public access](/docs/infrastructure/object-storage/buckets/bucket-policies#public-access)). > **Info** > > **Bucket name tip:** match the bucket name to your domain (e.g., `app.ibee.ai`) for clarity. It does not affect functionality. ### 3. Configure the AWS CLI Set up a profile pointing at IBEE Object Storage: ```bash aws configure --profile ibee # AWS Access Key ID: # AWS Secret Access Key: # Default region: us-east-1 # Default output format: json ``` ### 4. Upload your build output Sync the build folder to your bucket. Replace ``, ``, and `./dist` with your values — the full endpoint is the **S3 Endpoint** shown when you created the credential: ```bash aws s3 sync ./dist s3:/// \ --endpoint-url https://.blob.ibeestorage.com \ --profile ibee \ --acl public-read \ --delete ``` The `--delete` flag removes files from the bucket that no longer exist locally — useful for clean redeploys. ### 5. Set correct cache headers SPAs and static sites benefit from aggressive caching for hashed assets and no caching for `index.html`. Re-upload `index.html` with a short TTL after the sync: ```bash aws s3 cp ./dist/index.html s3:///index.html \ --endpoint-url https://.blob.ibeestorage.com \ --profile ibee \ --acl public-read \ --cache-control "no-cache, no-store, must-revalidate" \ --content-type "text/html" ``` This ensures users always get the latest `index.html` (which references new hashed asset filenames), while the hashed assets themselves can be cached for a year by the CDN. ### 6. Create a CDN distribution Put a CDN in front of the bucket for HTTPS, custom domains, and global edge caching ([CDN integration](/docs/infrastructure/object-storage/cdn-integration)). * **Origin Type:** Object Storage Bucket → select your bucket * **Cache Policy:** Static Assets (1 year) You'll get a CDN URL like `dl-abc123.cdn.ibee.ai`. **SPA deep links:** for a single-page app, open the distribution's **Overview** tab, tick **Enable SPA** on the **Single-page application (SPA)** card, and click **Save**. The CDN then serves `index.html` for page routes such as `/dashboard/settings`; requests for missing files still return 404. The API equivalent is `PUT /cdn/distributions/{distribution_id}/website-config` (`index_document`, default `index.html`). ### 7. Add a custom domain Create a CNAME at your DNS provider, then add your domain (e.g., `app.ibee.ai`) on the distribution's detail page ([CDN → Custom domains](/docs/network-security/cdn#custom-domains)): | Type | Name | Value | | ----- | ----- | ------------------- | | CNAME | `app` | `cname.cdn.ibee.ai` | SSL is auto-provisioned within a few minutes of DNS propagating. ## Verify Visit your custom domain — you should see your site over HTTPS. For SPAs, open a few routes directly (e.g. `/about`) to confirm they load. ```bash curl -I https://app.ibee.ai # HTTP/2 200 # content-type: text/html # cache-control: no-cache, no-store, must-revalidate ``` ## Redeploying Each deploy is a fresh sync: ```bash npm run build aws s3 sync ./dist s3:/// \ --endpoint-url https://.blob.ibeestorage.com \ --profile ibee --acl public-read --delete aws s3 cp ./dist/index.html s3:///index.html \ --endpoint-url https://.blob.ibeestorage.com \ --profile ibee --acl public-read \ --cache-control "no-cache" --content-type "text/html" ``` If hashed asset filenames changed, the CDN serves the new `index.html` immediately (because of `no-cache`), which then references the new assets — no manual cache invalidation needed. ## Troubleshooting **Site loads on CDN URL but not on custom domain** DNS hasn't propagated yet, or the CNAME points at the bucket instead of the CDN URL. Use `dig app.ibee.ai CNAME +short` to confirm it returns `cname.cdn.ibee.ai`. **SPA returns 404 on refresh of nested routes** Turn on **Enable SPA** on the distribution's **Overview** tab (see the SPA note under Step 6), or switch the app to hash-based routing. **Stale content after redeploy** Hashed asset filenames should bust caches automatically. If you're seeing the old `index.html`, confirm the `Cache-Control: no-cache` header is set on it (Step 5). **Mixed content / blocked HTTP requests** Ensure all internal API calls and asset URLs use HTTPS. Browsers block HTTP subresources on HTTPS pages. **CORS errors when calling APIs from the site** Configure CORS on the API or the bucket ([CORS](/docs/infrastructure/object-storage/buckets/cors)). ## Related pages * [Create a bucket](/docs/infrastructure/object-storage/buckets) * [Upload and download objects](/docs/infrastructure/object-storage/objects) * [CDN integration](/docs/infrastructure/object-storage/cdn-integration) * [Custom domains](/docs/infrastructure/object-storage/buckets/custom-domains) * [CORS](/docs/infrastructure/object-storage/buckets/cors) --- title: CDN Integration url: https://ibee.ai/docs/infrastructure/object-storage/cdn-integration description: Front an IBEE Object Storage bucket with the IBEE CDN to cache and deliver content globally with low latency. last_updated: 2026-10-27 --- # CDN Integration > Front an IBEE Object Storage bucket with the IBEE CDN to cache and deliver content globally with low latency. Use a CDN distribution with an **Object Storage Bucket** origin to put a global cache in front of your bucket. Static files, media, and other assets are served from edge nodes closer to your users, reducing latency and origin load. CDN distributions are managed under **Network & Security → CDN** in the portal. For the full reference — every cache policy, custom domains, purging, the SPA setting, metrics, and troubleshooting — see [Network & Security → CDN](/docs/network-security/cdn). ## Before you begin * An active IBEE Solutions organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)) * An Object Storage bucket with files to distribute ([Create a bucket](/docs/infrastructure/object-storage/buckets)) ## Front a bucket with the CDN ### 1. Open CDN In the portal, click **CDN** in the left sidebar under **Network & Security**. ### 2. Open the Create dialog Click **+ Create CDN**. The **Create CDN Distribution** dialog opens. ### 3. Fill in the fields | Field | Value | | ------------------- | ----------------------------------------------------------------------- | | **Name** | e.g. `assets-prod` | | **Origin Type** | **Object Storage Bucket** | | **Select a bucket** | Pick the bucket to front (use the searchable dropdown) | | **Cache Policy** | `Static Assets` for long-lived assets, or `Media Files` for video/audio | ### 4. Save Click **Create Distribution**. The distribution is provisioned and assigned a CDN URL like `dl-{hash}.cdn.ibee.ai` with an automatic SSL certificate. > **Info** > > To serve the CDN from your own hostname (e.g. `cdn.example.com`) instead of the default `dl-{hash}.cdn.ibee.ai`, create a CNAME record from your subdomain to `cname.cdn.ibee.ai`, then click **Add Domain** on the distribution's detail page — see [CDN → Custom domains](/docs/network-security/cdn#custom-domains). Don't use the bucket's own [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) setting for this: a bucket custom domain serves the bucket directly and bypasses the CDN cache. ## Cache policy quick reference | Policy | TTL | Best for | | ----------------- | ------- | --------------------------- | | **Static Assets** | 1 year | Images, fonts, CSS, JS | | **Media Files** | 30 days | Video and audio | | **Short Cache** | 1 hour | Frequently changing content | | **No Cache** | None | Always fetches from origin | See [Network & Security → CDN](/docs/network-security/cdn#choose-a-cache-policy) for full details. ## Related pages * [Network & Security → CDN](/docs/network-security/cdn) * [Buckets](/docs/infrastructure/object-storage/buckets) * [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) * [Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies) --- title: Pricing url: https://ibee.ai/docs/infrastructure/object-storage/pricing description: IBEE Object Storage pricing — storage, internet egress, API operation classes, included monthly usage, rate limits, and billing examples. last_updated: 2026-09-28 --- # Pricing > IBEE Object Storage pricing — storage, internet egress, API operation classes, included monthly usage, rate limits, and billing examples. IBEE Object Storage charges based on the total volume of data stored, internet egress, and two classes of API operations: 1. [Class A operations](#class-a-operations) which are more expensive and generally write or mutate state. 2. [Class B operations](#class-b-operations) which generally read existing data. Uploads are free. Traffic between Object Storage and IBEE services in the same region is free. All included usage is on a monthly basis. ### Plans | Plan | Included Storage | Included Egress | Included API Requests | | -------- | ---------------- | --------------- | ---------------------------------------------- | | **Free** | 25 GB / month | 50 GB / month | 1 million Class A + 10 million Class B / month | Included usage resets each month. Once your included usage is exhausted, usage is charged at the pay-as-you-go rates below. ### Pay-as-you-go rates | Usage | Price | | ------------------------------------------- | ----------------------- | | Storage | ₹1.5 / GB | | Internet egress | ₹2 / GB | | Class A operations | ₹420 / million requests | | Class B operations | ₹35 / million requests | | Ingress (uploads) | Free | | Traffic to IBEE services in the same region | Free | ## Storage usage Storage is billed using **GB-month** as the billing metric. This means charges depend on both the amount of data stored and how long it is stored during the billing period. For example: * Storing **1 GB** for a full month = **1 GB-month** * Storing **10 GB** for a full month = **10 GB-months** * Storing **5 GB** for half a month = **2.5 GB-months** These are illustrative examples to explain how storage billing works. ### Class A operations Class A operations include write and mutation requests billed at ₹420 / million: `ListBuckets` `PutBucket` `ListObjects` `PutObject` `CopyObject` `CompleteMultipartUpload` `CreateMultipartUpload` `LifecycleStorageTierTransition` `ListMultipartUploads` `UploadPart` `UploadPartCopy` `ListParts` `PutBucketEncryption` `PutBucketCors` `PutBucketLifecycleConfiguration` ### Class B operations Class B operations include read and retrieval requests billed at ₹35 / million: `HeadBucket` `HeadObject` `GetObject` `UsageSummary` `GetBucketEncryption` `GetBucketLocation` `GetBucketCors` `GetBucketLifecycleConfiguration` ## Free and unmetered usage * Uploads into Object Storage are free. * Traffic between Object Storage and IBEE services in the same region is free. * Internet egress is billed only after any included plan usage is exhausted. * API request charges apply only after the included monthly request limits are exceeded. * Ingress is free, but subject to fair-use protections and abuse prevention controls to help keep the platform reliable for all users. * Accounts with unusually high or abusive upload activity may be rate limited or reviewed. ## Rate limits | Operation | Default limit | | ------------------------------------------ | ------------------------ | | Public downloads | 1,000 req/sec per domain | | S3 API reads (`GET Object`) | 500 req/sec | | S3 API writes (`PUT Object`, `UploadPart`) | 40 req/sec | | S3 metadata / control operations | 50 req/sec | Public downloads are available through the bucket's Public Access URL (`dl-{bucketId}.blob.dev`, rate-limited and not intended for production) or your own custom domain. > **Info** > > **Custom domains** are a separately billed add-on. When you add one, the portal checks your organization's billing status first. See [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains). > **Info** > > These are default platform limits. If you expect sustained high request rates or large public download volumes, contact support. ## Billing examples ### Free plan example If an account stores **8 GB** throughout the month, uses **20 GB** of internet egress, makes **500,000 Class A requests**, and makes **5 million Class B requests** in a month, the estimated cost for the month would be: | Usage | Included quantity | Billable quantity | Price | Total | | ------------------ | ----------------- | ----------------- | -------------- | ------ | | Storage | 25 GB-months | 0 GB-months | ₹1.5 / GB | ₹0 | | Internet egress | 50 GB | 0 GB | ₹2 / GB | ₹0 | | Class A operations | 1 million | 0 | ₹420 / million | ₹0 | | Class B operations | 10 million | 0 | ₹35 / million | ₹0 | | **TOTAL** | | | | **₹0** | ### Pay-as-you-go example If an account stores **200 GB** throughout the month, uses **500 GB** of internet egress, makes **5 million Class A requests**, and makes **50 million Class B requests** in a month, the included monthly usage from the [Plans](#plans) table is applied first and the rest is billed at pay-as-you-go rates: | Usage | Included quantity | Billable quantity | Price | Total | | ------------------ | ----------------- | ----------------- | --------------- | ------------- | | Storage | 25 GB-months | 175 GB-months | ₹1.5 / GB-month | ₹262.50 | | Internet egress | 50 GB | 450 GB | ₹2 / GB | ₹900 | | Class A operations | 1 million | 4 million | ₹420 / million | ₹1,680 | | Class B operations | 10 million | 40 million | ₹35 / million | ₹1,400 | | **TOTAL** | | | | **₹4,242.50** | ## Frequently asked questions #### What is included in the Free plan? See the [Plans](#plans) table above for the storage, egress, and request allowances included each month. #### When do included usage limits reset? Included usage resets monthly. #### What happens after I exceed included usage? Standard pay-as-you-go pricing applies: Storage ₹1.5/GB-month, Internet egress ₹2/GB, Class A requests ₹420/million, and Class B requests ₹35/million. #### Is uploading data free? Yes. Ingress (uploads) is always free. We do not charge for data uploaded into Object Storage. #### What is internet egress? Internet egress is data transferred from Object Storage to the internet — for example, downloading files, serving files publicly, or transferring data to external systems. #### Is traffic to other IBEE services free? Yes. Traffic between Object Storage and IBEE services in the same region is free. #### What are Class A and Class B operations? API operations are billed in two categories. Class A covers write and mutation operations such as uploads and multipart upload writes. Class B covers read and retrieval operations such as downloads and metadata reads. #### Are there rate limits? Yes. Default limits are 1,000 req/s per domain for public downloads, 500 req/s for `GET Object`, 40 req/s for `PUT Object` and `UploadPart`, and 50 req/s for metadata and control operations. #### Can rate limits be increased? Yes. If you have a legitimate high-volume workload, contact support to discuss higher limits. #### Are free uploads unlimited? Ingress is free but subject to fair-use protections and abuse prevention controls. Accounts with unusually high or abusive upload activity may be rate limited or reviewed to protect platform reliability. ## Related pages * [Create a bucket](/docs/infrastructure/object-storage/buckets) * [API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Lifecycle policies](/docs/infrastructure/object-storage/buckets/lifecycle-management) * [Permissions and policies](/docs/infrastructure/object-storage/buckets/bucket-policies) --- title: Limits url: https://ibee.ai/docs/infrastructure/object-storage/limits description: Hard limits for IBEE Object Storage — storage per bucket, object size, upload size, API rate limits, bucket naming rules, and free tier caps. Limits in GiB and TiB are base-2. last_updated: 2026-09-28 --- # Limits > Hard limits for IBEE Object Storage — storage per bucket, object size, upload size, API rate limits, bucket naming rules, and free tier caps. Limits in GiB and TiB are base-2. Limits specified in GiB (gibibyte) or TiB (tebibyte) are storage units based on base-2. 1 GiB = 2³⁰ bytes. This is distinct from 1 GB (gigabyte) = 10⁹ bytes. ## Storage and object limits | Feature | Limit | | ------------------------------------------------------- | -------------------------------------------------------------- | | Data storage per bucket | Unlimited | | Number of objects per bucket | Unlimited | | Maximum buckets per account | 1,000,000 | | Maximum bucket management operations per bucket 1 | 50 per second | | Number of custom domains per bucket | 50 | | Object key length | 1,024 bytes | | Object metadata size | 8,192 bytes | | Object size 2 | 5 TiB per object | | Maximum upload size 3 | 5 GiB (single-part) / 4.995 TiB (multi-part) 4 | | Maximum upload parts | 10,000 | | Maximum file size for uploads through the portal | 300 MB per file — use an S3-compatible client for larger files | | Maximum concurrent writes to the same object name (key) | 1 per second 5 | ## API rate limits | Operation | Limit | | ------------------------------------------ | ---------------------- | | Public downloads | 1,000 req/s per domain | | S3 API reads (`GET Object`) | 500 req/s | | S3 API writes (`PUT Object`, `UploadPart`) | 40 req/s | | S3 metadata / control operations | 50 req/s | ### Public download domain (`dl-{bucketId}.blob.dev`) The `dl-{bucketId}.blob.dev` domain is intended for testing only and has a variable rate limit applied. * If you exceed the rate limit, requests will be temporarily throttled and you will receive a `429 Too Many Requests` response. * Bandwidth may also be throttled when using the `dl-{bucketId}.blob.dev` endpoint. For production, connect a [custom domain](/docs/infrastructure/object-storage/buckets/custom-domains) to your bucket. Custom domains allow you to serve content from a hostname you control (e.g. `assets.example.com`) with no throttling on the default domain. ## S3 credential limits | Limit | Value | | ------------------------- | ------------------------------------------------------------------------------------ | | Workspaces per credential | 1 | | Expiry | None — S3 credentials stay valid until you revoke them on the **S3 Credentials** tab | ## Free tier caps | Resource | Free tier | | ---------------- | ------------------ | | Storage | 25 GB | | Internet egress | 50 GB / month | | Class A requests | 1 million / month | | Class B requests | 10 million / month | Usage beyond these caps is charged at [pay-as-you-go rates](/docs/infrastructure/object-storage/pricing#pay-as-you-go-rates). ## Need a higher limit? To request an increase to any limit, [contact support](/docs/support/contact-support). If the limit can be raised for your account, the support team will follow up with next steps. ## Related pages * [Pricing](/docs/infrastructure/object-storage/pricing) * [Create a bucket](/docs/infrastructure/object-storage/buckets) * [API Tokens](/docs/infrastructure/object-storage/api-tokens) * [Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) --- title: Block Storage url: https://ibee.ai/docs/infrastructure/block-storage description: Persistent NVMe volumes you can attach to IBEE Solutions servers — create, attach, mount, detach, and delete block storage volumes. last_updated: 2026-10-19 --- # Block Storage > Persistent NVMe volumes you can attach to IBEE Solutions servers — create, attach, mount, detach, and delete block storage volumes. Block Storage volumes are persistent NVMe disks you can attach to any IBEE Solutions server. They live independently of the server, so the data survives if the server is rebuilt, resized, or deleted. Use them for databases, application state, file shares, or anywhere you need durable storage that outlives the compute. Volumes are managed under **Infrastructure → Block Storage** in the portal. ## Key concepts | Concept | What it means | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Volume** | A single NVMe block device with a fixed provisioned size. | | **Storage type** | **NVMe SSD**. (**Standard HDD** is listed as coming soon.) | | **Site** | The location the volume is provisioned in. A volume can only be attached to servers in the same location. | | **Performance tier** | Set by the volume's size — **Standard** for smaller volumes, **High Performance** for larger ones (above 500 GB). | | **Class** | Storage class shown on the volume — `Balanced` for the standard NVMe tier. | | **Replicas** | Number of replicas the platform keeps for durability. Default: `2`. | | **Volume name** | The display name. At least 3 characters; lowercase letters, numbers, and hyphens only. | | **Status** | `Ready` (idle), `In Use` (attached to a server), `Resizing` (a size increase is running). | | **Attachment** | Which server the volume is currently attached to (if any), and the device path inside the guest (e.g. `/dev/vdc`). | ## What you can do #### [Create a volume](/docs/infrastructure/block-storage/create-a-volume) Provision a new NVMe volume — pick a site, size, and name. Also covers resizing and deleting a volume. #### [Attach and detach](/docs/infrastructure/block-storage/attach-and-detach-a-volume) Connect a volume to a server, format and mount it (Linux or Windows), and safely detach when done. You can increase a volume's size later, from the volume's page — see [Resize a volume](/docs/infrastructure/block-storage/create-a-volume#resize-a-volume). Volumes can't be shrunk. ## Limits and behavior * **Maximum size:** set by the storage plan for the site — currently up to 2,000 GB per volume. * **Minimum size:** 10 GB per volume. * **Grow only:** a resize can only increase the size. Expand the filesystem inside the server afterwards. * **Region-bound:** A volume can only be attached to servers in the same region as the volume. * **One server at a time:** A volume can be attached to a single server; detach before reattaching elsewhere. * **Delete on Termination:** `No` by default — volumes survive when their attached server is deleted. * **Data path:** Inside the guest the volume appears as `/dev/vdb`, `/dev/vdc`, … — the exact path is shown on the volume's **Mount Instructions** tab once attached. ## Typical workflow 1. **Create** the volume in the same region as your server. 2. **Attach** the volume to the server — the portal assigns a device path. 3. **Mount** it inside the guest (format on first use, then mount and add to `/etc/fstab`). 4. **Use** it — read, write, snapshot. 5. When you no longer need it, **unmount** in the guest, **detach** in the portal, and optionally **delete** the volume. ## Related pages * [Create a volume](/docs/infrastructure/block-storage/create-a-volume) * [Attach and detach a volume](/docs/infrastructure/block-storage/attach-and-detach-a-volume) * [Snapshots](/docs/tools/snapshots) --- title: Create a volume url: https://ibee.ai/docs/infrastructure/block-storage/create-a-volume description: Provision a new NVMe block storage volume on IBEE Solutions — pick storage type, location, size, and a label — then resize or delete it. last_updated: 2026-10-27 --- # Create a volume > Provision a new NVMe block storage volume on IBEE Solutions — pick storage type, location, size, and a label — then resize or delete it. A Block Storage volume is a persistent NVMe disk that lives independently of your servers. Once created, it can be attached to any IBEE Solutions server in the same region. ## Before you begin * An active IBEE Solutions organization with a verified account ([Verify your account](/docs/getting-started/account-setup/verify-your-identity)) * KYC verification completed — Block Storage requires full account verification * Sufficient wallet credits — the platform checks your billing state before creating a volume ([Billing and usage](/docs/platform-fundamentals/billing-and-usage)) > **Warning** > > If your account shows a **Limited Access** banner, complete KYC verification to unlock full access to Block Storage. ## Create a volume ### Open Block Storage In the portal sidebar, click **Block Storage** under **Infrastructure**. If you have no volumes yet, the page shows a **No block volumes yet** empty state with an **+ Add Volume** button. Otherwise, click **+ Add Volume** in the top right. ### Choose a storage type Under **Storage Type**, select **NVMe SSD** (marked **Recommended**) — high-performance NVMe storage. **Standard HDD** is shown as **Coming Soon** and can't be selected yet. ### Choose a site Under **Site**, click the card for the location you want. Each card shows the location name and its site code. > **Info** > > The volume can only be attached to servers in the same location. Pick the site of the server you intend to attach to. ### Set the volume size Under **Volume Size**, use the slider, the quick-size buttons, or **Custom Size** to enter an exact value. The minimum is **10 GB**; the maximum and the quick sizes come from the storage plan for the chosen site (currently up to **2,000 GB**). Performance depends on the size you pick. The **Performance** row in the summary shows the tier for the current size: | Tier | Typical profile | | -------------------- | --------------------------------------------------------------- | | **Standard** | Smaller volumes — about 5,000 IOPS and 125 MiB/s | | **High Performance** | Larger volumes (above 500 GB) — about 10,000 IOPS and 400 MiB/s | The exact thresholds and figures come from the storage plan and are shown in the portal as you change the size. The price panel shows the per-GB rate (**size x rate/GB**) and the estimated monthly and hourly cost. Volumes are billed per GB provisioned per month. ### Name the volume Under **Volume Details**, enter a **Volume Name** — the display name for the volume in the portal. * At least 3 characters * Lowercase letters, numbers, and hyphens only * Example: `my-db-volume`, `redis-data`, `web-uploads` ### Create the volume Check the summary (**Storage Type**, **Location**, **Size**, **Performance**, **Volume Name**) and click **Create Volume**. The platform first runs a billing check against your organization's wallet. If it doesn't pass, an error explains why (for example, insufficient wallet balance) — add credits and try again. A toast confirms the volume is being created (for example *Volume "my-db-volume" is being created*), and the portal opens the new volume's detail page. The volume shows **Creating** and then **Ready** within a few seconds. ## Volume details Click any volume in the list to open its detail page. It has two tabs, **Overview** and **Mount Instructions**. The **Overview** tab shows: | Field | Description | | --------------- | ------------------------------------------------------ | | **Volume Name** | The name you entered. | | **Size** | Provisioned capacity. | | **Class** | Storage class — `Balanced` for the standard NVMe tier. | | **Location** | The site the volume lives in. | | **Replicas** | Number of replicas the platform keeps. | | **Created** | Creation timestamp. | | **Volume ID** | Unique identifier, with a copy button. | Below the details is the attachment section. A new volume shows an **Attach to Server** button; once attached, the section is titled **Attached To**. ## Resize a volume You can increase a volume's size at any time. A volume can't be made smaller. ### Open the resize dialog Open the volume and click **Resize volume** in the top right, or **Increase size** next to **Size** on the **Overview** tab. From the volume list, open the actions menu and choose **Resize Volume**. ### Pick the new size Enter a **New size** in GB or click a quick size. The dialog shows the range allowed by the volume's storage plan (**Increase only**). For a valid size it shows a quote: the **Current** and **New** monthly price and the **Monthly change**. Billing changes only after the resize succeeds. ### Check the attached server If the volume is attached to a running server, the dialog asks you to stop or suspend the server first and refresh, which uses the safer offline path. Where the server supports it, you can instead tick *I understand the risk and want to resize while the server is running.* ### Resize Tick *I understand that volume size can only be increased and that I must expand the guest filesystem after the resize.* and click the **Resize to** button, which shows the new size (for example **Resize to 200 GB**). The volume shows **Resizing**, then a toast confirms the new size (*Volume resized to 200 GB*). ### Expand the filesystem The extra space can't be used until you grow the filesystem inside the server. When the resize finishes, the dialog shows the commands for **Linux · ext4**, **Linux · XFS**, and **Windows**. Confirm the device and partition with `lsblk -f` first — layouts differ. ```bash lsblk -f # If the filesystem is inside a partition, grow that partition first sudo growpart /dev/ 1 # ext4 sudo resize2fs /dev/ # XFS (pass the mount point) sudo xfs_growfs /mnt/data df -h ``` On Windows, open **Disk Management**, choose **Action > Rescan Disks**, right-click the volume, and choose **Extend Volume**. ## Delete a volume ### Unmount and detach Unmount the volume inside the guest, then detach it in the portal ([Detach a volume](/docs/infrastructure/block-storage/attach-and-detach-a-volume#detach-a-volume)). The **Delete** button on the volume's detail page refuses attached volumes with *"Detach this volume from all servers before deleting."* ### Delete Click **Delete** in the top right of the volume's detail page, or open the volume's actions menu in the list and choose **Delete**. The **Delete Volume** dialog warns that *all data will be permanently erased*. Click **Delete** to confirm. > **Warning** > > Deleting a volume is permanent and cannot be undone. If you delete a still-attached volume from the list's actions menu, the dialog first asks you to confirm *I have unmounted this volume inside the server before deleting.* ## Use the API The same actions are available in the public API (scopes `block-storage.read` and `block-storage.write`): `POST /block-storage/volumes` (`name`, `size_gb`, `site_id`), `GET /block-storage/volumes`, `GET /block-storage/volumes/{volume_id}`, `POST /block-storage/volumes/{volume_id}/resize` (`new_size_gb`; for an attached volume also `vm_state` and `allow_online`), `GET /block-storage/volumes/{volume_id}/operations` to follow a resize, and `DELETE /block-storage/volumes/{volume_id}`. The resize price quote has no API operation; use the portal to see it. ## Troubleshooting **Billing error when clicking Create Volume** The billing check didn't pass — for example, your wallet balance doesn't cover the volume, or billing needs attention. Add credits or settle outstanding usage under **Billing**, then try again. **Limited Access banner visible** Complete KYC verification to unlock full Block Storage access. **Usage limit reached** If the create form shows a **"Limit reached"** indicator, your organization has hit its block storage quota. Click the link to request an increase under **Billing → Usage Limits**. **"Lowercase letters, numbers, and hyphens only" error** Volume names can't contain spaces, dots, underscores, or uppercase characters, and must be at least 3 characters. Use a hyphen-separated lowercase name. **Volume stuck in creating state** Refresh the page. If the volume does not reach **Ready** within a few minutes, contact IBEE support. ## Next steps * [Attach the volume to a server](/docs/infrastructure/block-storage/attach-and-detach-a-volume) * [Snapshots](/docs/tools/snapshots) — capture a server's root disk and attached volumes --- title: Attach and detach a volume url: https://ibee.ai/docs/infrastructure/block-storage/attach-and-detach-a-volume description: Attach a Block Storage volume to an IBEE Solutions server, mount it inside the guest, and safely detach when you're done. last_updated: 2026-10-19 --- # Attach and detach a volume > Attach a Block Storage volume to an IBEE Solutions server, mount it inside the guest, and safely detach when you're done. Attaching a volume connects it to a server so the OS sees it as a disk device (e.g. `/dev/vdc`). The portal handles the attach itself; you then format and mount the volume inside the guest using the commands on the **Mount Instructions** tab. ## Before you begin * A **Ready** Block Storage volume ([Create a volume](/docs/infrastructure/block-storage/create-a-volume)) * A running IBEE Solutions server in the **same region** as the volume * SSH access to that server (Remote Desktop or PowerShell access for Windows servers) ## Attach a volume ### Open the volume In the portal, go to **Block Storage** and click the volume you want to attach. ### Click Attach to Server On the **Overview** tab, scroll to the **Attached To** section. For an unattached volume you'll see **Not attached to any server** with an **Attach to Server** button. Click **Attach to Server**. ### Pick a server In the **Attach Volume** dialog, under **Select Server**, pick a server. The list shows the Cloud VMs and GPU VMs in the volume's location, each with a **Cloud** or **GPU** badge and its status. Use **Search servers...** to filter it. Click **Attach to Server**. The button shows **Attaching...** while the platform connects the volume. ### Confirmation A toast confirms the attach (for example *Volume "my-db-volume" attached*). The volume status changes to **In Use**, and the **Attached To** section now shows the server's UUID, the device path (e.g. `Device: /dev/vdc`), and a **Detach** button. ## Mount the volume (Linux) After attaching, open the **Mount Instructions** tab on the volume detail page. It shows a green confirmation panel: > **Volume is attached — run these commands inside your server.** > Device: `/dev/vdc` on server `` Copy the device path from the panel — that's the placeholder you replace below. SSH into the server and run the **Mounting** commands: ```bash # 1. Check the disk is visible lsblk # 2. Format (FIRST TIME ONLY — skip if volume already has data) sudo mkfs.ext4 /dev/vdc # 3. Create mount point sudo mkdir -p /mnt/data # 4. Mount sudo mount /dev/vdc /mnt/data # 5. Verify df -h /mnt/data # 6. Make persistent across reboots UUID=$(sudo blkid -s UUID -o value /dev/vdc) echo "UUID=$UUID /mnt/data ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab ``` > **Warning** > > Step 2 (`mkfs.ext4`) **erases everything on the volume**. Only run it on a brand-new volume. Skip it for any volume that already has data. If the device path on your **Mount Instructions** tab is something other than `/dev/vdc` (e.g. `/dev/vdb`), substitute it everywhere in the commands above. ## Mount the volume (Windows) For a Windows server, the **Mount Instructions** tab shows Windows steps instead — the confirmation reads *"Volume is attached — prepare it inside Windows."* — with both a Disk Management walkthrough and PowerShell scripts. **Using Disk Management:** 1. Connect to the Windows VM using Remote Desktop. 2. Open **Disk Management**, or **Server Manager → File and Storage Services → Disks**. 3. Bring the new disk online if Windows shows it as offline. 4. Initialize the disk as **GPT** (new empty volumes only). 5. Create a **New Simple Volume**, assign a drive letter, and format it with **NTFS**. 6. Verify the drive is **Healthy** and visible in File Explorer. **Using PowerShell (run as Administrator) — new empty disk:** ```powershell # 1. Find the newly attached disk Get-Disk | Sort-Object Number | Format-Table Number,FriendlyName,Size,OperationalStatus,PartitionStyle # 2. Set the disk number from the output above $DiskNumber = Set-Disk -Number $DiskNumber -IsOffline $false Set-Disk -Number $DiskNumber -IsReadOnly $false # 3. New empty disk only: initialize, format, and assign drive F: Initialize-Disk -Number $DiskNumber -PartitionStyle GPT New-Partition -DiskNumber $DiskNumber -UseMaximumSize -DriveLetter F | Format-Volume -FileSystem NTFS -NewFileSystemLabel "IBEEData" -Confirm:$false # 4. Verify the drive Get-Volume -DriveLetter F ``` **Using PowerShell — existing disk that already has data:** ```powershell Get-Disk | Sort-Object Number | Format-Table Number,FriendlyName,Size,OperationalStatus,PartitionStyle $DiskNumber = Set-Disk -Number $DiskNumber -IsOffline $false Set-Disk -Number $DiskNumber -IsReadOnly $false Get-Partition -DiskNumber $DiskNumber | Where-Object DriveLetter -Eq $null | Select-Object -First 1 | Set-Partition -NewDriveLetter F Get-Volume -DriveLetter F ``` > **Warning** > > `Initialize-Disk` and `Format-Volume` **erase everything on the disk**. Only run them on a brand-new volume. ## Detach a volume > **Warning** > > **Always unmount the volume inside the guest before detaching in the portal.** Detaching a mounted volume can cause data corruption or filesystem errors. ### 1. Unmount inside the guest SSH into the server and run the **Unmounting** commands from the **Mount Instructions** tab: ```bash # 1. Sync pending writes sync # 2. Unmount sudo umount /mnt/data # 3. Remove from fstab sudo sed -i '/\/mnt\/data/d' /etc/fstab # 4. Verify unmounted lsblk ``` `lsblk` should no longer show the device mounted on `/mnt/data`. On a **Windows** server, take the disk offline instead. Close any apps using the drive, then run in PowerShell as Administrator: ```powershell $DriveLetter = "F" $DiskNumber = (Get-Partition -DriveLetter $DriveLetter).DiskNumber Set-Disk -Number $DiskNumber -IsOffline $true ``` ### 2. Detach in the portal ### Open the volume Go to **Block Storage** and click your volume. The **Attached To** section shows the server and device path. ### Click Detach Click **Detach**. The **Detach Volume** dialog opens. ### Confirm unmount Tick the **I have unmounted this volume from the server before detaching** checkbox. The **Detach** button is disabled until you check it. ### Detach Click **Detach**. A toast confirms **Volume detached from ``**. After detaching, the volume status returns to **Ready** and the **Attached To** section reverts to **Not attached to any server**. You can now reattach it to any other server in the same region. ## Mount Instructions tab states The **Mount Instructions** tab content changes depending on attachment state: | State | What's shown | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Not attached** | Orange **Attach first, then mount** banner explaining that the device path will appear once attached. The mounting commands use `/dev/` as a placeholder. | | **Attached** | Green **Volume is attached — run these commands inside your server** confirmation with the actual device path (`/dev/vdc`). Both **Mounting** and **Unmounting** scripts are shown. | ## Use the API Attach with `POST /compute/cloud-vms/{vm_id}/actions/attach-volume` (GPU VMs: `POST /compute/gpu-vms/{vm_id}/actions/attach-volume`). The body needs `volume_id` and `billing_catalog` (`sku_id` and `sku_code` of the volume's Block Storage plan; no public operation lists them yet). Detach with the matching `.../actions/detach-volume` operation, sending `volume_id` and `confirm_unmounted: true` after you unmount the volume. ## Troubleshooting **No servers listed in the Attach dialog** You don't have a running server in the same region as the volume. Either start a server in that region or create a new volume in your server's region. **Device path not shown in Mount Instructions** The device path appears only after the attach completes. Wait a few seconds and refresh the page. **`lsblk` doesn't show the new disk** Confirm the attach succeeded (volume status should be **In Use**). If the platform shows attached but the OS doesn't see it, reboot the server. **Mount doesn't persist after reboot** Re-run step 6 of the Mounting script and verify the UUID with `sudo blkid /dev/vdc`. The line in `/etc/fstab` should match the actual UUID. **Detach button disabled** Tick the unmount confirmation checkbox in the Detach dialog. The button stays disabled until that's confirmed. **Detach fails or hangs** The volume is still in use by the guest. Run `sudo lsof /mnt/data` to find processes holding the mount, stop them, then `sudo umount /mnt/data` again before retrying detach. ## Related pages * [Create a volume](/docs/infrastructure/block-storage/create-a-volume) * [Delete a volume](/docs/infrastructure/block-storage/create-a-volume#delete-a-volume) * [Snapshots](/docs/tools/snapshots) --- title: Container Registry url: https://ibee.ai/docs/infrastructure/container-registry description: Store Docker and OCI images in private or public registries, push and pull with registry access tokens, and review vulnerability and SBOM data for every image. last_updated: 2026-10-20 --- # Container Registry > Store Docker and OCI images in private or public registries, push and pull with registry access tokens, and review vulnerability and SBOM data for every image. Container Registry stores Docker and OCI images for a workspace. Each registry has its own namespace on the shared IBEE registry endpoint: ```text registry.ibee.ai//: ``` Any Docker- or OCI-compatible client works, including Docker, Podman, containerd, Kubernetes, and CI systems. Every image you push is scanned for vulnerabilities and gets a software bill of materials (SBOM) automatically. > **Info** > > Container Registry is enabled per organization. If **Container Registry** is not in your sidebar, contact [support](/docs/support/contact-support) to request access. ## Before you begin * An organization with billing set up ([Add billing](/docs/getting-started/account-setup/add-billing)). Each registry is created with a paid storage plan. * A workspace to hold the registry. * Docker (or another OCI client) on the machine that pushes or pulls images. ## Create a registry ### Open Container Registry Select your organization and workspace, then click **Container Registry** under **Infrastructure** in the sidebar. Click **Create registry**. ### Name the registry Enter a **Registry name**. The portal checks availability as you type. * 3–48 characters: lowercase letters, numbers, and hyphens. * Must start with a letter and end with a letter or number. * Names are unique across IBEE and cannot be changed later. A deleted registry's name is never reassigned. * Names that are reserved for the platform, such as names starting with `ibee-`, are rejected. ### Choose visibility | Visibility | Who can pull | Best for | | --------------------- | ----------------------------------------------------- | ------------------------------- | | **Private** (default) | Only clients that log in with a registry access token | Application and internal images | | **Public** | Anyone, without logging in | Images you publish for others | Pushing always requires an access token with push permission, whatever the visibility. Outbound bandwidth from anonymous pulls of a public registry is billed to your workspace. ### Choose a storage plan Pick a **Storage plan**. Each plan is a fixed monthly storage quota; the portal shows the plans available to your organization with their monthly price and the outbound bandwidth price per GB. Storage uses decimal units (1 GB = 1,000,000,000 bytes). ### Create Review the summary at the bottom of the page and click **Create registry**. The registry appears in the list as **Provisioning**, then **Active**. If Billing doesn't approve the plan (for example, an initial wallet top-up is required or the balance is too low), a **Billing needs attention** dialog explains why. Add credits under **Billing** and try again. Plan upgrades are checked the same way. ## Registry list and status The registry list shows each registry's name and endpoint, visibility, status, and creation date. | Status | Meaning | | ---------------- | ---------------------------------------------------------------------------- | | **Provisioning** | The registry is being created. | | **Active** | Ready for pushes and pulls. | | **Updating** | A change such as a plan upgrade is being applied. | | **Deleting** | Deletion has started. | | **Failed** | The last operation did not complete. Contact support if it does not recover. | Click a registry to open it. The detail page has four tabs: **Overview**, **Security**, **Metrics**, and **Settings**. ## Create a registry access token Docker clients authenticate with a **registry access token**, not with your IBEE account password or a platform API token. ### Open registry access tokens On the registry's **Overview** tab, click **Create access token**. This opens **API Tokens → Registry access tokens** at the organization level with the registry preselected. You can also open that tab directly from the organization's **API Tokens** page. ### Fill in the token details | Field | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Token name** | Lowercase letters, numbers, and hyphens, for example `production-k8s`. Must be unique among the organization's active tokens. | | **Workspace** and **Registry** | The registry the token can access. | | **Registry permission** | **Pull and push** (the default) for developers and CI pipelines that publish images, or **Pull only** for servers and Kubernetes clusters that only run images. | | **Token expiration** | 7 days, 30 days, 90 days (default), 1 year, or **No expiration**. A token without expiration stays valid until you rotate or revoke it. | Click **Create token**. ### Save the credentials The portal shows the **Registry username** and the **Access token**. The access token is shown only once and cannot be recovered. Store both in your password manager or CI secret store, then click **I've saved my access token**. > **Tip** > > Use **Pull only** tokens for anything that only runs images. Give push access only to the pipelines that build them. ### Rotate or revoke a token The **Registry access tokens** tab lists every token with its registry, permission, creation date, and status (**Active**, **Expired**, or **Revoked**). * **Rotate** issues a new access token and immediately stops the current one from working. The new token is shown once. * **Revoke** removes the token's access immediately. Workloads that use it can no longer pull or push. ## Log in, push, and pull Log in with the registry username and access token. The username contains a `$` character, so wrap it in single quotes on the command line: ```bash docker login registry.ibee.ai --username '' # At the Password prompt, paste the registry access token. ``` In CI, keep the token in a secret such as `IBEE_REGISTRY_TOKEN` and pass it on standard input so it never appears in logs or shell history: ```bash printf '%s' "$IBEE_REGISTRY_TOKEN" | docker login registry.ibee.ai \ --username "$IBEE_REGISTRY_USERNAME" \ --password-stdin ``` Build and push an image: ```bash docker build -t registry.ibee.ai//: . docker push registry.ibee.ai//: ``` Push an image you already have locally: ```bash docker tag : registry.ibee.ai//: docker push registry.ibee.ai//: ``` Pull by tag, or by digest for an immutable reference: ```bash docker pull registry.ibee.ai//: docker pull registry.ibee.ai//@sha256: ``` A repository is created automatically on its first push. The **Overview** tab's **Docker instructions** section shows these commands with your registry's endpoint filled in. > **Info** > > `https://registry.ibee.ai/v2/` returns `401 Unauthorized` until a client logs in. That response is expected and confirms the endpoint is reachable. ### Pull from Kubernetes Create an image pull secret from a **Pull only** token and reference it from your workloads: ```bash kubectl create secret docker-registry ibee-registry \ --docker-server=registry.ibee.ai \ --docker-username='' \ --docker-password='' ``` ```yaml spec: imagePullSecrets: - name: ibee-registry containers: - name: app image: registry.ibee.ai//: ``` ## Repositories and images The **Overview** tab lists the registry's repositories with their artifact count, pull count, and last update time. Open a repository to see one row per image digest; tags are shown as aliases of the digest they point to. Open an image to copy its pull command by tag or by digest. ## Review image security Open a registry and click the **Security** tab. Vulnerability scanning and SBOM generation run automatically on every push, so there is nothing to configure. ### Vulnerabilities The summary shows the number of findings by severity. Click a severity to filter by it. You can also filter by: * **CVE or advisory ID** * **Severity** * **Repository** * **Image tag or digest** * **Package** Each finding shows the CVE, severity, repository and image, affected package, installed version, fixed version, and CVSS score. To scan an image again, click **Rescan** on a finding, or **Rescan artifact** in its details. The rescan runs against the exact image digest, and existing results stay visible until it completes. Rescanning requires write access to the workspace. ### SBOMs Select a repository to list its SBOMs, one per image digest. Several tags that point to the same digest share one row. Each row shows the SBOM status, when it was generated, its format (SPDX or CycloneDX), the package count, and the platform. Click **Components** to browse an SBOM. Search by name, version, license, supplier, or package URL, and inspect each package's type, license, supplier, and dependency relationships. ## Monitor usage The **Metrics** tab shows storage used, storage quota, quota utilization, and outbound bandwidth, with a bandwidth chart over the last 24 hours, 7 days, or 30 days. ## Upgrade the storage plan The **Settings** tab shows the current plan, its quota, and the outbound bandwidth price. To get more space, choose a larger plan under **Upgrade storage plan** and click **Upgrade plan**. While the change is applied, the tab shows **Upgrade in progress**. Plans can only be upgraded; downgrades are not supported. ## Billing * **Storage** is billed monthly for the plan you choose. * **Outbound bandwidth** is billed per GB. Private and public registries have separate rates, shown on the create page and on the **Settings** tab. ## Delete a registry In the registry list, click the delete icon on the registry's row and confirm **Delete registry**. Deletion permanently removes the registry's repositories, images, tags, and the access tokens scoped to it, and the registry name cannot be reused. A registry must be empty before it can be deleted. If deletion fails because the registry still contains images, contact [support](/docs/support/contact-support) to empty it. ## Use the API The **Container Registry** section of the [API reference](/docs/api-reference/introduction) manages the same registries as the portal. Pushes and pulls still go through `registry.ibee.ai` with a registry access token, not through the API. Calls need a platform API token with `container-registry.read` for reads or `container-registry.write` for changes, and the `workspace_id` query parameter. All paths start with `https://api.ibee.ai/v1/container-registry`. | Task | Operation | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Check a name | `GET /registry-names/{registry_name}/availability` | | List, create | `GET`, `POST /registries` | | Get, delete | `GET`, `DELETE /registries/{registry_id}?confirm_registry_name=` | | Change visibility | `PATCH /registries/{registry_id}/visibility` | | Retry a failed change | `POST /registries/{registry_id}/reconcile` | | Empty before deleting | `POST /registries/{registry_id}/empty?confirm_registry_name=` | | Storage plan, upgrade | `GET /registries/{registry_id}/package`, `POST /registries/{registry_id}/upgrade` | | Registry access tokens | `GET`, `POST /registries/{registry_id}/access-tokens`; `POST …/access-tokens/{token_id}/rotate`; `DELETE …/access-tokens/{token_id}` | | Repositories | `GET /registries/{registry_id}/repositories`; `DELETE …/repositories/{repository_name}?confirm=true` | | Images | `GET /registries/{registry_id}/artifacts?repository_name=`; `DELETE …/artifacts/{reference}`; `POST …/artifacts/{reference}/scan` | | Pull policy | `GET`, `PATCH /registries/{registry_id}/security/settings` | | Vulnerabilities | `GET /registries/{registry_id}/security/vulnerabilities/summary`, `GET …/security/vulnerabilities` | | SBOMs | `GET /registries/{registry_id}/security/sboms`, `GET …/sboms/{artifact_digest}`, `GET …/sboms/{artifact_digest}/download` | | Metrics | `GET /registries/{registry_id}/metrics?range=24h` | Things to know: * **Create and upgrade take a storage plan SKU** in `billing_catalog.sku_code`. Billing checks it, as in the portal; a refusal returns `403` with `billing_resource_not_eligible` and a `reason`. * **Create can return `202`** while provisioning finishes. Poll the registry until `observed_state` is `ACTIVE`. * **Upgrade needs an `Idempotency-Key` header.** Retrying with the same key and plan returns the original operation. * **Lists are paged** with `page` and `page_size` (at most 100). * **Access token secrets are returned once**, by create and rotate. ## Related pages * [API Tokens](/docs/tools/api-tokens) * [Cloud VMs](/docs/infrastructure/cloud-vms) * [Secret Manager](/docs/tools/secret-manager): store registry credentials for deployment pipelines --- title: Load Balancers url: https://ibee.ai/docs/network-security/load-balancer description: Distribute traffic across multiple backends with L4 and L7 load balancers on IBEE Solutions — health checks, routing algorithms, and TLS termination. last_updated: 2026-10-26 --- # Load Balancers > Distribute traffic across multiple backends with L4 and L7 load balancers on IBEE Solutions — health checks, routing algorithms, and TLS termination. An IBEE Solutions Load Balancer distributes incoming traffic across multiple backends so your application stays available when a single server fails or is overloaded. Each load balancer gets a stable endpoint (host and port) that you point your clients or DNS at; the load balancer forwards traffic to healthy backends only. ## Layers Choose the layer when you create the load balancer: | Layer | Protocols | Use for | | -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- | | **L7** (application) | HTTP, HTTPS | Web apps and APIs — path- and header-based routing, sticky sessions, TLS termination | | **L4** (transport) | TCP, TLS passthrough | Databases, message queues, custom TCP protocols, or end-to-end encryption where the backend terminates TLS | ## Capabilities | Capability | Details | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Backends | Route to a `service`, an `ip`, or a `hostname` target — each with its own port and weight | | Routing algorithms | `round_robin`, `least_request`, `random`, `consistent_hash` ([Algorithms](/docs/network-security/load-balancer/algorithms)) | | Health checks | Active HTTP, HTTPS, or TCP checks with configurable thresholds ([Health checks](/docs/network-security/load-balancer/health-checks)) | | TLS | Managed certificate termination on L7 HTTPS, or TLS passthrough on L4 ([SSL and TLS termination](/docs/network-security/load-balancer/ssl-and-tls-termination)) | | Sticky sessions | Header-based session affinity on L7 | | Retries | Automatic retries on `5xx`, connection reset, and connect failure | | L7 rules | Priority-ordered path-prefix and header-match routing rules | | Proxy protocol | Forward client connection metadata so compatible backends see the original client IP | ## Endpoint After creation, the load balancer's detail page shows its public endpoint — **Host**, **Listener port**, and the full **Public host** URL. Point your application or a DNS record at this endpoint. ## Manage load balancers The portal does not support editing a load balancer after creation. To change backends, routing, health checks, or any other setting, delete the load balancer from the list and create a new one ([Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer#delete-a-load-balancer)). ## Related pages * [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer) * [Attach VMs as backends](/docs/network-security/load-balancer/attach-vms) * [Health checks](/docs/network-security/load-balancer/health-checks) * [Firewalls](/docs/network-security/firewalls) --- title: Create a load balancer url: https://ibee.ai/docs/network-security/load-balancer/create-a-load-balancer description: Create an L4 or L7 load balancer on IBEE Solutions — choose a protocol, add backends, set the routing algorithm, and configure health checks. last_updated: 2026-10-27 --- # Create a load balancer > Create an L4 or L7 load balancer on IBEE Solutions — choose a protocol, add backends, set the routing algorithm, and configure health checks. Create a load balancer from the portal in a few minutes. Choose the layer and protocol, add one or more backends, and set routing and health-check behavior. Optional behaviors — sticky sessions, proxy protocol, automatic retries, and L7 routing rules — are on the same form. ## Before you begin * A verified IBEE Solutions organization — creation requires identity verification ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)) * The address and port of at least one backend (a Cloud VM private IP, a hostname, or a service name) > **Info** > > The portal cannot edit a load balancer after it is created. To change its backends, routing, health checks, or other settings in the portal, delete it and create a new one. ## Create a load balancer ### Open Load Balancers In the portal sidebar, click **Load Balancer** under **Network & Security**, then click **Create Load Balancer**. ### Set the traffic profile | Field | Description | | ------------ | -------------------------------------------------------------------------------------------- | | **Name** | Unique per account — e.g. `orders-gateway` | | **Layer** | **Layer 7** for HTTP/HTTPS or **Layer 4** for TCP and TLS passthrough | | **Protocol** | Layer 7: **HTTPS** (default) or **HTTP** · Layer 4: **TCP** (default) or **TLS passthrough** | ### Add backends Add one row per backend. Click **Add backend** for more. | Field | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Type** | **Service** (default), **IP address**, or **Hostname**. Hostnames must be fully qualified domain names. | | **Target** | The service name, IP address, or hostname — e.g. `orders-service` or `10.8.0.12` | | **Port** | Backend port, `1`–`65535` (default `8080`) | | **Weight** | Relative share of traffic, `1`–`1000` (default `100`) — a backend with weight `200` receives twice the traffic of one with weight `100` | Tick **Encrypt traffic from the load balancer to this backend** if the load balancer should connect to that backend over TLS. ### Configure routing and health In **Routing and health**, select a **Routing algorithm** — **Round robin** (default), **Least request**, **Random**, or **Consistent hash** — and a **Request timeout** in milliseconds (default `30000`, allowed `100`–`300000`). Set the **Active health check**: | Field | Default | | -------------------------- | ---------------------------------- | | **Type** | **HTTP** (also **HTTPS**, **TCP**) | | **Path** (HTTP/HTTPS only) | `/health` | | **Interval (ms)** | `10000` | | **Timeout (ms)** | `2000` | | **Healthy threshold** | `2` consecutive passes | | **Unhealthy threshold** | `3` consecutive failures | Interval and timeout accept `100`–`120000` ms; thresholds accept `1`–`20`. ### Set advanced behavior * **Sticky sessions** (Layer 7 only) — route requests with the same header value to the same backend. Set the **Sticky header name** (default `X-User-ID`). * **Proxy protocol** — forward client connection metadata to compatible backends so they see the original client IP. * **Automatic retries** — retry requests that fail with a `5xx` response, a connection reset, or a connection failure. Set **Attempts** (default `3`, allowed `1`–`10`) and **Per-retry timeout (ms)** (default `5000`, allowed `100`–`120000`). * **L7 routing rules** (Layer 7 only) — click **Add rule** for each priority-ordered rule. Each rule has a **Priority**, a **Path prefix** (e.g. `/api`), and an optional **Header name** and **Header value** match. With no rules, all requests use the default `/` route. ### Create Click **Create Load Balancer**. You are redirected to the load balancer's detail page, which shows its status and public endpoint. ## Detail page Click a load balancer in the list to open its detail page. The header shows the layer, protocol, and current status. The page has these sections: | Section | Contents | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Overview** | Name, namespace, load balancer ID, and last-updated time | | **Public endpoint** | Host, listener port, and public URL (with copy and open buttons); for a load balancer with a custom domain, also the **Custom domain** and its **CNAME target** | | **Backends** | Type, target, port, weight, and TLS for every backend | | **L7 routing rules** | Priority, path prefix, and header matches (Layer 7 only) | Click **Refresh** to re-poll status. If provisioning fails, a **Provisioning error** message appears on the page. ## Delete a load balancer On the **Load Balancers** list, click the delete icon on the load balancer's row, then click **Delete** to confirm. Deletion is permanent. ## Use the API | Task | Operation | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Create | `POST /networking/load-balancers/l4`, `POST /networking/load-balancers/l7` | | List, get, or check status | `GET /networking/load-balancers`, `GET /networking/load-balancers/{load_balancer_id}`, `GET /networking/load-balancers/{load_balancer_id}/status` | | Update the name, backends, routing, TLS, and (L7) rules and custom domain | `PATCH /networking/load-balancers/l4/{load_balancer_id}`, `PATCH /networking/load-balancers/l7/{load_balancer_id}` | | Delete | `DELETE /networking/load-balancers/{load_balancer_id}` | The API create and update operations have no fields for the health check, request timeout, retries, or proxy protocol. Set these by creating the load balancer in the portal. ## Troubleshooting **"Backend port must be between 1 and 65535"** Each backend needs a valid numeric port. **Creation blocked with a verification message** Complete identity verification — the create button is disabled until your organization is verified. **Status stays in a provisioning state** Click **Refresh** on the detail page. If a **Provisioning error** appears, delete the load balancer, fix the reported issue, and create it again; otherwise contact support. **Need to change a setting** The portal cannot edit a load balancer in place. Delete the load balancer and create a new one with the updated settings, then point your clients or DNS at the new endpoint. ## Related pages * [Load balancer overview](/docs/network-security/load-balancer) * [Algorithms](/docs/network-security/load-balancer/algorithms) * [SSL and TLS termination](/docs/network-security/load-balancer/ssl-and-tls-termination) * [Attach VMs as backends](/docs/network-security/load-balancer/attach-vms) --- title: Algorithms url: https://ibee.ai/docs/network-security/load-balancer/algorithms description: Choose how an IBEE Solutions load balancer distributes requests — round robin, least request, random, or consistent hash — and when to combine them with weights and sticky sessions. last_updated: 2026-10-26 --- # Algorithms > Choose how an IBEE Solutions load balancer distributes requests — round robin, least request, random, or consistent hash — and when to combine them with weights and sticky sessions. The routing algorithm decides which backend receives each request. Set it as the **Routing algorithm** in the **Routing and health** section when you create a load balancer. Backend **weights** apply on top of every algorithm — a backend with weight `200` receives twice the share of one with weight `100`. ## Available algorithms | Algorithm | How it works | Best for | | ------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- | | **Round robin** (`round_robin`) *(default)* | Cycles through backends in order | Evenly sized backends serving uniform requests | | **Least request** (`least_request`) | Sends each request to the backend with the fewest active requests | Mixed request durations — keeps slow requests from piling onto one backend | | **Random** (`random`) | Picks a backend at random | Large backend pools where per-request state isn't worth tracking | | **Consistent hash** (`consistent_hash`) | Hashes the request so the same client keys map to the same backend | Cache-friendly workloads where repeat hits should land on the same backend | ## Sticky sessions On Layer 7 load balancers, enable **Sticky sessions** to pin a client to one backend across requests. Affinity is header-based: requests carrying the same value in the **Sticky header name** header (default `X-User-ID`) always route to the same backend. Use sticky sessions when your application keeps per-user state in memory. Prefer stateless backends where possible — stickiness reduces how evenly load spreads. ## Weights Every backend has a **Weight** from `1` to `1000` (default `100`). Use uneven weights to: * Split traffic between versions (e.g. `90` / `10` canary) * Send more traffic to larger instances in a mixed pool Weights are set when you create the load balancer. The portal cannot edit a load balancer in place — to change weights there, delete it and create a new one with the new values. ## Related pages * [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer) * [Health checks](/docs/network-security/load-balancer/health-checks) * [Attach VMs as backends](/docs/network-security/load-balancer/attach-vms) --- title: Health checks url: https://ibee.ai/docs/network-security/load-balancer/health-checks description: Configure active HTTP, HTTPS, or TCP health checks on an IBEE Solutions load balancer so traffic only reaches healthy backends. last_updated: 2026-10-19 --- # Health checks > Configure active HTTP, HTTPS, or TCP health checks on an IBEE Solutions load balancer so traffic only reaches healthy backends. The load balancer actively probes every backend on a fixed interval. A backend that fails enough consecutive probes is removed from rotation; it returns automatically once it passes again. Health checks are configured under **Active health check** in the **Routing and health** section of the create form, and cannot be changed after creation. The API has no health check fields, so set them in the portal. ## Check types | Type | What it verifies | | ------------------ | ------------------------------------------------------------------------------ | | `http` *(default)* | The backend returns a successful response for a GET on the configured **Path** | | `https` | Same as `http`, over TLS | | `tcp` | A TCP connection can be established on the backend port — no path involved | Use `http`/`https` whenever your service exposes a health endpoint — a TCP check only proves the port is open, not that the application can serve requests. ## Settings | Field | Default | Description | | ----------------------- | ---------- | ----------------------------------------------------------------------- | | **Path** | `/health` | Request path for `http`/`https` checks | | **Interval** | `10000` ms | Time between probes (`100`–`120000` ms) | | **Timeout** | `2000` ms | How long a probe waits before counting as a failure (`100`–`120000` ms) | | **Healthy threshold** | `2` | Consecutive passes before a backend re-enters rotation (`1`–`20`) | | **Unhealthy threshold** | `3` | Consecutive failures before a backend is removed (`1`–`20`) | With the defaults, a failing backend is removed after roughly 30 seconds (3 failures × 10 s interval) and restored about 20 seconds after it recovers. ## Choosing a health endpoint * Return `200` only when the service can actually do work (dependencies reachable, not just process-up). * Keep the endpoint fast and unauthenticated — it's probed every few seconds. * Don't reuse a heavy endpoint; a dedicated `/health` route avoids cache and auth side effects. ## Related pages * [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer) * [Algorithms](/docs/network-security/load-balancer/algorithms) --- title: SSL and TLS termination url: https://ibee.ai/docs/network-security/load-balancer/ssl-and-tls-termination description: Terminate HTTPS at an IBEE Solutions L7 load balancer with a managed certificate, or pass TLS through untouched on L4 for end-to-end encryption. last_updated: 2026-10-19 --- # SSL and TLS termination > Terminate HTTPS at an IBEE Solutions L7 load balancer with a managed certificate, or pass TLS through untouched on L4 for end-to-end encryption. How the load balancer handles encrypted traffic depends on the layer and protocol you pick at creation. There are two TLS modes: | Mode | Where you get it | Behavior | | --------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- | | **Terminate** | L7 with protocol `HTTPS` | The load balancer decrypts traffic with a **managed certificate**, then forwards to backends | | **Passthrough** | L4 with protocol `tls_passthrough` | Encrypted traffic is forwarded as-is — your backend holds the certificate and terminates TLS | ## Terminate at the edge (L7 HTTPS) Create an **L7** load balancer with protocol **HTTPS**. The platform provisions and manages the certificate — there is nothing to upload or renew. You cannot upload your own certificate. Traffic from the load balancer to your backends is plain HTTP by default. To re-encrypt the hop to a backend, tick **Encrypt traffic from the load balancer to this backend** on that backend row — the load balancer then connects to it over TLS. Use termination when you want: * Managed certificates with no renewal work * L7 features that need to read the request — path/header rules, sticky sessions ## Pass TLS through (L4) Create an **L4** load balancer with protocol **tls_passthrough**. The load balancer forwards encrypted bytes without decrypting, so: * Your backends present their own certificate and terminate TLS themselves * End-to-end encryption is preserved — the load balancer never sees plaintext * L7 features (path rules, header matches, sticky sessions) are not available, since the traffic can't be inspected Choose the health check type accordingly — with passthrough, use a **TCP** check, or an **HTTPS** check if the backend exposes a health endpoint over TLS. ## Use your own domain The detail page shows the load balancer's public endpoint **Host**. To serve traffic on your own domain, create a DNS record at your DNS provider that points your domain at that endpoint. The portal has no custom domain field. Through the API, you can set `custom_domain.hostname` on an L7 load balancer (`POST /networking/load-balancers/l7` or `PATCH /networking/load-balancers/l7/{load_balancer_id}`). The detail page then shows the **Custom domain** and its **CNAME target**; point a CNAME record for your domain at that target. ## Related pages * [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer) * [Health checks](/docs/network-security/load-balancer/health-checks) --- title: Attach VMs url: https://ibee.ai/docs/network-security/load-balancer/attach-vms description: Point an IBEE Solutions load balancer at your Cloud VMs or GPU VMs by adding them as IP or hostname backends. last_updated: 2026-10-26 --- # Attach VMs > Point an IBEE Solutions load balancer at your Cloud VMs or GPU VMs by adding them as IP or hostname backends. A load balancer routes to **backends** — each one a `service`, `ip`, or `hostname` target. To balance traffic across your virtual machines, add each VM as a backend using its IP address. ## Before you begin * Two or more running VMs in the same workspace serving the same application ([Create a VM](/docs/infrastructure/cloud-vms/create-a-vm)) * The application listening on the same port on every VM * A health endpoint on each VM (e.g. `/health`) so failed instances are removed automatically ## Add VMs as backends ### Collect the VM addresses Open each VM's detail page and note its IP address. Prefer private IPs when the VMs and load balancer share a network — traffic stays internal. ### Add a backend row per VM In the load balancer create form, add one row per VM: | Field | Value | | ---------------------------------------------------------- | --------------------------------------------------------------- | | **Type** | **IP address** — or **Hostname** if you address VMs by DNS name | | **Target** | The VM's IP address, e.g. `10.8.0.12` | | **Port** | The port your application listens on | | **Weight** | `100` for an equal split — adjust to shift traffic | | **Encrypt traffic from the load balancer to this backend** | Tick only if the VM serves TLS on that port | ### Verify distribution After creation, open the detail page — the **Backends** section lists every VM with its type, target, port, weight, and TLS setting. Send a few requests to the public endpoint and confirm they spread across VMs (watch your application logs, or include the hostname in a test response). ## Scaling the pool Unhealthy VMs are removed from rotation automatically by [health checks](/docs/network-security/load-balancer/health-checks) — you don't need to remove a VM that's temporarily down, and a VM you stop for maintenance drops out once it fails its checks. > **Info** > > The portal cannot edit the backend list after creation. To add or remove VMs permanently, or to change weights, delete the load balancer and [create a new one](/docs/network-security/load-balancer/create-a-load-balancer) with the updated backends, then point your clients or DNS at the new endpoint. ## Related pages * [Create a load balancer](/docs/network-security/load-balancer/create-a-load-balancer) * [Health checks](/docs/network-security/load-balancer/health-checks) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) --- title: CDN url: https://ibee.ai/docs/network-security/cdn description: Distribute content globally with IBEE CDN. Cache an Object Storage bucket at edge locations for low-latency delivery, with automatic SSL, custom domains, purging, and traffic metrics. last_updated: 2026-10-19 --- # CDN > Distribute content globally with IBEE CDN. Cache an Object Storage bucket at edge locations for low-latency delivery, with automatic SSL, custom domains, purging, and traffic metrics. The IBEE CDN caches your content at edge locations around the world so users get fast load times no matter where they are. Front an **IBEE Object Storage bucket** with a distribution. Each distribution gets a CDN URL in the format `dl-{hash}.cdn.ibee.ai` and an automatically-provisioned SSL certificate. ## Use cases * Accelerate static assets (images, CSS, JS) for websites. * Reduce origin server load by caching responses at the edge. * Add a TLS-terminated edge in front of an Object Storage bucket — see [Object Storage → CDN integration](/docs/infrastructure/object-storage/cdn-integration). * Host a static site or single-page app from a bucket — see [Static Site Hosting](/docs/infrastructure/object-storage/static-site-hosting). ## Before you begin * An active IBEE Solutions organization with a verified account * A bucket with content to serve, with **Public Access** turned on ([Bucket policies](/docs/infrastructure/object-storage/buckets/bucket-policies#public-access)). The bucket picker labels private buckets **Private**. ## Create a distribution ### 1. Open CDN In the IBEE Solutions portal, click **CDN** in the left sidebar under **Network & Security**. The page lives at `portal.ibee.ai/organizations/{orgId}/workspaces/{workspaceId}/cdn`. ### 2. Open the Create dialog Click **+ Create CDN** at the top right. The **Create CDN Distribution** dialog opens with the subtitle *"Configure origin and caching."* If no distributions exist, the empty state shows *"No CDN Distributions — Create a distribution to cache and accelerate your content delivery."* ### 3. Fill in the fields | Field | Required | Description | | ---------------- | -------- | -------------------------------------------------------------------------- | | **Name** | Yes | Unique distribution name (placeholder: `my-cdn-distribution`). | | **Origin Type** | Yes | Choose **Object Storage Bucket**. See the note on **Custom Origin** below. | | **Cache Policy** | Yes | Select the caching behavior — defaults to `Static Assets`. | ### 4. Pick an origin type **Object Storage Bucket** — *"Use an existing bucket from your storage."* Pick a bucket from the **Select a bucket** dropdown (searchable). Only buckets in the current organization are listed. > **Warning** > > The form also offers **Custom Origin** (*"Use any external HTTPS website or server"*, with **IP address/Domain name** and **Port** fields), but creating a distribution with a custom origin does not work at the moment. Use an Object Storage bucket as the origin. ### 5. Choose a cache policy The **Cache Policy** dropdown offers four presets: | Policy | TTL | Best for | | ----------------------------- | ------- | -------------------------------------------------------------- | | **Static Assets** *(default)* | 1 year | Images, fonts, CSS, JS — long-lived assets that rarely change. | | **Media Files** | 30 days | Video and audio. | | **Short Cache** | 1 hour | Frequently changing content. | | **No Cache** | None | Always fetches from the origin. | ### 6. Save Click **Create Distribution**. The distribution is provisioned and assigned a CDN URL. > **Info** > > **Custom domains and SSL** > Custom domains can be added after the distribution is created. SSL certificates are automatically provisioned — no manual configuration required. ## Verify Your new distribution appears in the CDN list with these columns: | Column | Description | | ------------ | -------------------------------------- | | NAME | Distribution name | | ORIGIN | Source bucket | | CDN URL | Assigned URL — `dl-{hash}.cdn.ibee.ai` | | CACHE POLICY | Selected caching behavior | | STATUS | Active / Provisioning | | ACTIONS | Delete | Copy the **CDN URL** and use it to serve your content. Click a distribution's name to open its detail page. It has two tabs: * **Overview** — origin, cache policy, status, the default CDN URL, the **Single-page application (SPA)** setting, and the custom domains section. * **Metrics** — traffic for the distribution. See [Metrics](#metrics). ## Single-page apps On the **Overview** tab, the **Single-page application (SPA)** card serves *index.html* for page routes, so deep links such as `/dashboard/settings` load your app. Tick **Enable SPA** and click **Save**; untick it and save to turn it off. Requests for missing files still return 404. ## Metrics The **Metrics** tab shows traffic for **24 hours**, **7 days**, or **30 days**: * Totals for **Requests**, **Data delivered**, **Cache hit rate**, and **Avg. TTFB**. * **Traffic over time**, switchable between requests, data delivered, and TTFB. * **Response health** — counts of `2xx`, `3xx`, `4xx`, and `5xx` responses and the `4xx`/`5xx` error rates. * Cache status (hit, miss, bypass, dynamic) and breakdowns by **Content types**, **Countries**, **Device types**, **Cache statuses**, and **Response status codes**. A note shows whether the data for the range is complete or still being processed. ## Delete a distribution In the CDN list, click the delete icon in the **Actions** column. In the **Delete Distribution?** dialog, click **Delete**. This can't be undone. ## Custom domains Serve content from your own hostname (e.g. `cdn.example.com`) instead of the default CDN URL. ### Point your DNS at the CDN At your DNS provider, create a CNAME record from your subdomain to: ``` cname.cdn.ibee.ai ``` ### Add the domain On the distribution's detail page, click **Add Domain**, enter the subdomain you pointed at the CNAME target, and click **Add Domain**. Custom domains are a billable add-on, so the portal first checks your organization's billing; if billing doesn't approve it, an error explains why. ### Wait for validation The domain card shows **Pending** while the domain is validated over HTTP and an SSL certificate is provisioned — usually 5–15 minutes, up to 1 hour. If the card lists extra **TXT** or **CNAME** records, add those at your DNS provider too. Use **Verify** or **Check Status** on the card to re-check. ### Remove a custom domain On the distribution's detail page, click the delete icon on the domain's card. The domain is removed immediately, without a confirmation step. Remove the CNAME record at your DNS provider afterwards. ## Purge cached content Click **Purge CDN** on the distribution's detail page to remove cached content without waiting for TTLs to expire: | Purge type | Matches | Limit | | -------------------- | --------------------------------------------------------- | ----------- | | **URL** | Exact URLs or paths (e.g. `/images/logo.png`) | 30 entries | | **Hostname** | All assets under matching hostnames | 100 entries | | **Tag** | Assets served with a matching `Cache-Tag` response header | 100 entries | | **Prefix** | All assets under a directory (e.g. `/images/`) | 100 entries | | **Purge Everything** | The entire distribution cache | — | Separate multiple entries with commas or one per line. **Purge Everything** requires ticking a confirmation checkbox — it briefly increases origin load while the cache refills. ## Troubleshooting **Distribution not serving updated content** Cached objects live until the policy TTL expires. Use **Purge CDN** with a URL or prefix purge to refresh specific content immediately. **Creating a distribution with a custom origin fails** Custom origins don't work at the moment. Use an Object Storage bucket as the origin. **Custom domain stuck in Pending** Confirm the CNAME record points to `cname.cdn.ibee.ai` and any listed TXT records are added, then click **Verify**. DNS propagation can take up to an hour. **Cannot add a custom domain during creation** Custom domains are added after the distribution is created, from its detail page. ## Use the API The public API covers distributions (`GET /cdn/distributions`, `POST /cdn/distributions` with `name`, `origin_type`, `origin_id`, and `cache_policy`, `GET`, `PATCH`, and `DELETE /cdn/distributions/{distribution_id}`), the SPA setting (`GET`, `PUT`, and `DELETE /cdn/distributions/{distribution_id}/website-config`), custom domains (`GET` and `POST /cdn/distributions/{distribution_id}/custom-domains`, `GET` and `DELETE .../custom-domains/{domain}`, `POST .../custom-domains/{domain}/verify`), and `POST /cdn/distributions/{distribution_id}/purge`. Two operations have no portal equivalent: `PATCH` (rename, cache policy, enable or disable) and `POST /cdn/generate-url`, which returns a time-limited CDN URL for an object in a bucket. The **Metrics** tab has no API operation. ## Related pages * [Object Storage → CDN integration](/docs/infrastructure/object-storage/cdn-integration) * [Object Storage → Custom Domains](/docs/infrastructure/object-storage/buckets/custom-domains) * [Object Storage buckets](/docs/infrastructure/object-storage/buckets) --- title: Firewall as a Service url: https://ibee.ai/docs/network-security/firewalls description: Create reusable firewall groups with inbound rules to control traffic to your Cloud VMs and GPU VMs. last_updated: 2026-10-27 --- # Firewall as a Service > Create reusable firewall groups with inbound rules to control traffic to your Cloud VMs and GPU VMs. IBEE Solutions Firewalls let you define inbound traffic rules and attach them to your VMs. Each firewall group contains a set of rules that control which traffic is allowed or dropped before it reaches your server. Firewalls are managed from the portal sidebar under **Network & Security**. ## How firewalls work * A **firewall group** is a named collection of inbound rules. * Each rule specifies an action (accept or drop), a protocol, a port or port range, and a source. * A firewall group can be attached to multiple VMs. A VM is in one firewall group at a time. * New VMs are protected by a platform default firewall group. Attaching a VM to one of your firewall groups replaces the default for that VM; detaching it restores the default. ## Firewall group structure Select a firewall group to open it. It has three tabs: | Tab | Contents | | -------------------- | -------------------------------------------------------------------------- | | **IPv4 Rules** | Inbound rules for IPv4 traffic | | **IPv6 Rules** | Coming soon — IPv6 rules can't be added yet | | **Linked Instances** | VMs attached to this firewall group, and controls to attach or detach them | ## Rule components Each rule has the following fields: | Field | Options | | -------------- | ------------------------------------------------------------------------------------ | | **Action** | **accept** (allow traffic) or **drop** (block traffic) | | **Protocol** | Any, TCP, UDP, or ICMP | | **Port / App** | A port number, a range (e.g. `8000-9000`), or a common application; TCP and UDP only | | **Source** | **Anywhere** (`0.0.0.0/0`) or **Custom** CIDR/IP addresses | | **Notes** | Optional note describing the rule | ## Common application ports The **Port / App** picker offers common services: | Application | Protocol | Port | | ----------- | -------- | ---- | | SSH | TCP | 22 | | HTTP | TCP | 80 | | HTTPS | TCP | 443 | | MySQL | TCP | 3306 | | PostgreSQL | TCP | 5432 | | DNS (UDP) | UDP | 53 | | MS RDP | TCP | 3389 | ## System-managed rules Every new firewall group includes system-managed rules: all outbound traffic is allowed, and a final rule drops any inbound traffic that your rules don't accept. System-managed rules have no **Save** or delete controls and cannot be edited or deleted. The firewall page lists inbound rules only. ## Manage firewall groups The Firewalls list shows 10 groups per page with each group's description, rule count, linked instances, and last update. The platform default group is marked **(default)**. Click a group's name to open it; its page shows the **Group Rules** count (out of 50) and the number of **Linked Instances**. * **Create** — click **Create Firewall Group**, enter a **Group name** (e.g. `web-tier`), and click **Create Group**. * **Delete** — open the group's menu in the list, click **Delete**, and confirm. Deleting a firewall group cannot be undone. * **Copy ID** — the group's menu also copies the firewall group ID for use with the API. ## Linked instances The **Linked Instances** tab lists the VMs attached to the firewall group with their server name, public IP, status, and attach time. * **Attach** — search for an active instance and click **Attach**. If the VM is already in another firewall group, it moves to this one. * **Detach** — click **Detach** on the instance's row. The VM returns to the platform default firewall group. The default firewall group has no **Attach** or **Detach** controls; the network service attaches VMs to it automatically. ## Use the API | Task | Operation | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | List firewall groups | `GET /networking/firewall-groups` — returns 10 groups unless you set `limit` (up to `100`); use `offset` for later pages | | Get, create, or delete a group | `GET /networking/firewall-groups/{firewall_group_id}`, `POST /networking/firewall-groups`, `DELETE /networking/firewall-groups/{firewall_group_id}` | | Add, edit, or delete a rule | `POST /networking/firewall-groups/{firewall_group_id}/rules`, `PATCH` or `DELETE /networking/firewall-groups/{firewall_group_id}/rules/{firewall_rule_id}` | | List, attach, or detach VMs | `GET` or `POST /networking/firewall-groups/{firewall_group_id}/attachments`, `DELETE /networking/firewall-groups/{firewall_group_id}/attachments/{vm_id}` | In the API, a rule's `action` is `allow` or `drop` (the portal's **accept** is `allow`). The API also accepts egress rules (`direction: egress`) and a rule `priority`, which the portal does not show. ## Best practices * Allow only the ports you need — inbound traffic that no rule accepts is dropped. * Use **Custom** source CIDRs to restrict access to known IP ranges instead of **Anywhere**. * Keep SSH (port 22) access restricted to your office or VPN CIDR. * Review linked instances periodically to ensure the right VMs are protected. ## Related pages * [Create firewall rules](/docs/network-security/firewalls/create-firewall-rules) * [VPC](/docs/network-security/vpc-ip-management) * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) --- title: Create firewall rules url: https://ibee.ai/docs/network-security/firewalls/create-firewall-rules description: Add inbound firewall rules to control which traffic reaches your IBEE Solutions VMs. last_updated: 2026-09-28 --- # Create firewall rules > Add inbound firewall rules to control which traffic reaches your IBEE Solutions VMs. Firewall rules control inbound traffic to your VMs. Each rule specifies an action, a protocol, a port, and a source. Rules are added to a firewall group, which is then attached to one or more VMs. ## Before you begin * An active, verified IBEE Solutions organization * A firewall group — click **Create Firewall Group** on the Firewalls page if you don't have one ([Manage firewall groups](/docs/network-security/firewalls#manage-firewall-groups)) ## Add a rule ### Open Firewalls In the portal sidebar, click **Firewalls** under **Network & Security**. ### Select a firewall group Click the firewall group you want to add rules to. The group opens with the **IPv4 Rules** tab active. ### Add a new rule Click **Add rule**. A new rule row appears with the following fields: | Field | Default | Options | | -------------- | ----------- | -------------------------------------------------------------------------------------------- | | **Action** | accept | accept, drop | | **Protocol** | TCP | Any, TCP, UDP, ICMP | | **Port / App** | (empty) | Port number, range (e.g. `8000-9000`), or a common application. Applies to TCP and UDP only. | | **Source** | Anywhere | Anywhere (`0.0.0.0/0`), Custom | | **CIDR/IP** | `0.0.0.0/0` | One or more CIDR blocks or IP addresses when the source is Custom | | **Notes** | (empty) | Optional note describing the rule | ### Configure the rule 1. Select the **Action** — **accept** to allow traffic, **drop** to block it. 2. Choose a **Protocol** — Any, TCP, UDP, or ICMP. 3. For TCP or UDP, enter a port number or range, or pick a common application: SSH (22), HTTP (80), HTTPS (443), MySQL (3306), PostgreSQL (5432), DNS (UDP 53), or MS RDP (3389). 4. Set the **Source** — **Anywhere** allows all IPs, or choose **Custom** and enter one or more CIDR blocks or IP addresses. 5. Optionally add a **Note**. ### Save the rule Click **Save** on the rule's row. Each rule is saved individually and takes effect on all VMs attached to this firewall group. ## IPv6 rules IPv6 rules are coming soon. The **IPv6 Rules** tab does not accept rules yet. ## Edit or delete a rule * To **edit**, change any field in the rule row and click **Save** on that row. * To **delete**, click the delete icon on the rule row. The rule is removed immediately — there is no separate save step. > **Warning** > > System-managed rules cannot be edited or deleted. They have no **Save** or delete controls. ## Example: allow web traffic To allow HTTP and HTTPS from anywhere, add and save two rules: | Action | Protocol | Port | Source | | ------ | -------- | ---- | -------- | | accept | TCP | 80 | Anywhere | | accept | TCP | 443 | Anywhere | ## Example: restrict SSH to an office IP | Action | Protocol | Port | Source | | ------ | -------- | ---- | ------------------------ | | accept | TCP | 22 | Custom: `203.0.113.0/24` | ## Troubleshooting **Cannot edit a rule** System-managed rules are read-only. You can only edit or delete rules you created. **Changes not taking effect** Make sure you clicked **Save** on each new or changed rule row. Unsaved rows are not applied. **Custom source validation error** Enter valid CIDR notation (e.g. `10.0.0.0/8`) or a single IP address. At least one CIDR or IP is required when using Custom source. ## Related pages * [Firewalls overview](/docs/network-security/firewalls) * [Linked instances](/docs/network-security/firewalls#linked-instances) --- title: VPC url: https://ibee.ai/docs/network-security/vpc-ip-management description: Create isolated private networks, subnets, NAT gateways, port forwarding rules, and VM attachments on IBEE Solutions. last_updated: 2026-10-27 --- # VPC > Create isolated private networks, subnets, NAT gateways, port forwarding rules, and VM attachments on IBEE Solutions. A VPC (Virtual Private Cloud) is an isolated Layer 3 network for resources in one workspace. Resources in the same VPC communicate over private IPs without traversing the public internet. A VPC belongs to one location, and only VMs in that location can attach to it. ## Create a VPC ### Open VPCs In the portal sidebar, click **VPC** under **Network & Security**, then click **Create VPC**. ### Enter the VPC details Enter a **Name** (e.g. `production-vpc`), choose a **Location**, and optionally add a **Description**. ### Choose connectivity | Option | Behavior | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Private only** *(default)* | VMs receive private addresses only. To expose one specific VM, attach a [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) to it later. | | **Managed NAT Gateway** | Private VMs share one public IPv4 address for outbound internet. Unsolicited inbound traffic is not accepted unless you add a [port forwarding rule](#nat-port-forwarding). | The VPC network and its default subnet are included at no extra charge. A managed NAT gateway is billed while it exists; the summary panel shows its price for the selected location before you create the VPC. Firewall rules still control access to each VM. ### Choose the private IP range * **Automatic** *(default)* picks a conflict-free RFC1918 range. * **Custom CIDR** — enter a **Network address** (e.g. `10.10.0.0`) and pick a **Network size** from `/22` to `/28` (default `/24`). The range must be RFC1918 space (`10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`) and aligned to the chosen size. If the address is not aligned, the form suggests the nearest valid network address. VPC ranges in the same account cannot overlap. ### Create Click **Create VPC Network**. IBEE creates the VPC with a default subnet (and, for **Managed NAT Gateway**, the NAT gateway). The VPC is usable when its status is `available`. ## Connectivity modes | Portal option | API `connectivity_type` | Use it for | | ----------------------- | ----------------------- | ------------------------------------------------------------ | | **Private only** | `private` | Private networking; expose individual VMs with a Reserved IP | | **Managed NAT Gateway** | `nat_gateway` | Private VMs that share managed outbound internet access | If an API request omits `connectivity_type`, the VPC is created as `public`: attached VMs keep their own public interface and also receive a private VPC interface. The portal does not offer this mode. NAT gateway controls (the gateway card and **Add Port Forwarding**) appear only on VPCs created with **Managed NAT Gateway**. ## VPC detail page The VPC list has a search box, a location filter, and **Refresh**. Click a VPC in the list to open it. The page has four tabs — **Overview**, **Subnets**, **Attached Nodes**, and **Reserved VIPs** — and an **Actions** menu with **Attach Node**, **Add Subnet**, **Add Port Forwarding** (NAT VPCs only), **Refresh**, and **Delete VPC**. **Overview** shows the VPC details (name, location, private CIDR, connectivity, creation time, VPC ID, and description). On a NAT VPC it also shows the NAT gateway and its port forwarding rules. ## Subnets ### Add a subnet 1. Click **Actions → Add Subnet** (or **Add Subnet** on the **Subnets** tab). 2. Enter a **Name** and a **CIDR**. The CIDR must be a sub-range of the VPC range that does not overlap another subnet. 3. Click **Create Subnet**. ### Delete a subnet On the **Subnets** tab, click the delete icon on the subnet row. The subnet is deleted right away, with no confirmation step. Detach any nodes that use the subnet first. ### Private IP ledger The **Subnets** tab also lists every reserved and allocated address in the VPC with its subnet, record type, owner, and status. Network and broadcast addresses are reserved implicitly by each subnet. ## Attach a VM ### Open Attach Node Click **Actions → Attach Node** (or **Attach Node** on the **Attached Nodes** tab). ### Choose the node and subnet Select a **Node** — only VMs in the VPC's location that are not already attached are listed — and a **Subnet**. ### Choose the private IP Under **Private IP assignment**, choose: * **Automatic** — the next free address in the subnet is claimed for the VM. * **Specific address** — enter an unused host address inside the subnet. The network, broadcast, and gateway addresses are rejected. ### Choose traffic routing (NAT VPCs) On a NAT VPC, if the VM already has a network connection, choose: * **Use VPC for internet** — internet and private traffic go through the VPC and its NAT gateway. The VM's current public IP stays connected until you remove it from the VM's networking settings. * **Private traffic only** — the VM keeps its current internet connection and uses the VPC only for private traffic. A VM with no other network connection uses the VPC as its primary network. If the VM already has a network connection and the VPC is **Private only**, the VPC carries private traffic only. ### Attach Click **Attach Node**. The dialog follows the attachment status until it completes. The **Attached Nodes** tab lists each VM with its status, VPC address, subnet, and access type (**Private**, **NAT**, or **Public IP**). ### Detach a VM On the **Attached Nodes** tab, click the detach icon on the VM's row, then confirm **Detach VM** in the **Detach VPC Interface** dialog. You can attach the VM again later. > **Warning** > > A VPC interface that is the VM's only network path cannot be detached. Give the > VM another network path first (for example, attach it to another VPC and use > that VPC for internet), then detach this one. ## NAT gateway A **Managed NAT Gateway** VPC starts with one NAT gateway. The **Overview** tab shows the gateway's status and public IP, and whether that IP is a platform-assigned NAT IP or one of your Reserved IPs. ### Use a Reserved IP To give the gateway a stable address you control, click **Use Reserved IP** (or **Replace Reserved IP**) on the gateway card, select an unattached Reserved IP in the same workspace and location, and click **Attach Reserved IP**. Existing port forwarding rules move to the new address. A previous Reserved IP returns to your Reserved IP pool; a platform-assigned address is released. ### Delete the NAT gateway Click **Delete NAT Gateway** on the gateway card. The dialog shows the impact: * VMs routed through the gateway lose outbound internet access. Private VPC connectivity remains. * All port forwarding rules on the gateway are permanently deleted. * NAT gateway billing stops after deletion. Choose what happens to the gateway's public IP: | Choice | Result | | ------------------------ | --------------------------------------------------------------------------------------------------------- | | **Reserve this NAT IP** | Keep the platform-assigned address as a Reserved IP (billed as a Reserved IP; the dialog shows the price) | | **Keep in Reserved IPs** | Shown when the gateway uses one of your Reserved IPs — it is detached and stays reserved | | **Release this IP** | Return the address to the platform pool. You may not get it back. | If VMs or rules are affected, tick the confirmation checkbox. Then click **Delete Gateway & Reserve IP** (or **Delete Gateway & Release IP**). ### Create a NAT gateway again After a NAT gateway is deleted, the **Overview** tab shows **Create NAT Gateway** (when VMs are attached, the **Attached Nodes** tab also offers **Add Managed NAT**). Choose a **Public IP** — **Automatic NAT IP** (assigned and released with the gateway) or one of your unattached Reserved IPs — and click **Create NAT Gateway**. Attached VMs use the new gateway without changing their VPC interfaces or private IPs. Deleted port forwarding rules are not restored. ## NAT port forwarding Port forwarding routes a public port on the NAT gateway to a private service. ### Open the rule form Click **Actions → Add Port Forwarding**, or **Add Rule** in the **NAT Port Forwarding** section of the **Overview** tab. ### Fill in the rule | Field | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Rule name** | e.g. `SSH access` | | **Protocol** | **TCP** or **UDP** | | **External port** | Public port on the NAT gateway, `1`–`65535`. Each protocol and external port can be used by only one rule. | | **Destination type** | **Private VM** — one NAT-connected VM address, or **MetalLB VIP** — a [Virtual IP](/docs/network-security/vpc-ip-management/virtual-ips) announced by cluster nodes | | **Internal IP** / **MetalLB VIP** | The attached VM or reserved VIP to forward to | | **Internal port** | Port on the destination, `1`–`65535` | | **Note** | Optional reason for the inbound access | | **Enable this rule** | The public endpoint accepts traffic once the rule is active | The form previews the traffic path, for example `203.0.113.10:2222 → 10.10.0.5:22`. ### Save Click **Add Rule**. Each rule row has **Edit**, **Enable**/**Disable**, and **Delete** actions. When editing, click **Save Changes** to apply. ## Use the API First call `GET /networking/sites?workspace_id=607005` and copy the exact `site_id` from an entry where `available` is `true`. A site ID is an opaque identifier, not a region name. ```bash curl -X POST \ "https://api.ibee.ai/v1/networking/vpcs?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "production", "site_id": "68b99bd78a8eda32ff3f16ea", "auto_cidr": true, "create_default_subnet": true, "connectivity_type": "nat_gateway" }' ``` Other VPC operations: | Task | Operation | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Rename a VPC or change its description | `PATCH /networking/vpcs/{vpc_id}` | | Add or delete a subnet | `POST /networking/vpcs/{vpc_id}/subnets`, `DELETE /networking/vpcs/{vpc_id}/subnets/{subnet_id}` | | Attach or detach a VM | `POST /networking/vpcs/{vpc_id}/nodes`, `DELETE /networking/vpcs/{vpc_id}/nodes/{vm_id}` | | Create or delete a NAT gateway | `POST /networking/vpcs/{vpc_id}/nat-gateways`, `DELETE /networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}` | | Add, edit, or delete a port forwarding rule | `POST /networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules`, `PATCH` or `DELETE /networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules/{port_forwarding_rule_id}` | These portal options have no API field or operation: **Use Reserved IP** on a NAT gateway, the public IP choice when deleting a NAT gateway, **Specific address** and traffic routing when attaching a VM, and the **MetalLB VIP** destination for port forwarding. ## Delete a VPC Before you delete a VPC: 1. Detach every VM on the **Attached Nodes** tab. 2. Delete the NAT gateway, if the VPC has one. 3. Delete every Virtual IP reservation on the **Reserved VIPs** tab. Subnets are removed automatically with the VPC. Then click **Actions → Delete VPC** and confirm. You can also delete a VPC from the VPC list; its dialog checks dependencies. If the VPC has a NAT gateway and no attached VMs, it offers **Delete NAT Gateway first**, which releases a platform-assigned NAT IP (a Reserved IP stays reserved). To keep the NAT IP, delete the gateway from the **Overview** tab and choose **Reserve this NAT IP**. The API returns `409 Conflict` while dependencies remain. ## Related pages * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips) * [Virtual IPs](/docs/network-security/vpc-ip-management/virtual-ips) * [Firewalls](/docs/network-security/firewalls) * [API reference](/docs/api-reference/introduction) --- title: Reserved IPs url: https://ibee.ai/docs/network-security/vpc-ip-management/reserved-ips description: Reserve portable public IPv4 addresses and attach them to VMs, NAT gateways, and Virtual IPs. last_updated: 2026-10-27 --- # Reserved IPs > Reserve portable public IPv4 addresses and attach them to VMs, NAT gateways, and Virtual IPs. Reserved IPs remain allocated to your workspace until you release them. You can detach an address from one VM and attach it to another for failover, maintenance, or a stable DNS endpoint. A Reserved IP can also serve as the public address of a [VPC NAT gateway](/docs/network-security/vpc-ip-management#nat-gateway) or give a [Virtual IP](/docs/network-security/vpc-ip-management/virtual-ips) public ingress. ## Reserve an address ### Open Reserved IPs In the portal sidebar, click **Reserved IPs** under **Network & Security**, then click **Reserve IP**. ### Choose how to reserve In the **Reserve a public IP** dialog, choose one of: * **Add New IP** — select a **Location**. IBEE assigns an available IPv4 address from that location's pool; you cannot enter an address manually. IPv4 is the only IP version available. * **Convert Existing IP** — select a VM's current public IPv4 under **Existing VM address** to keep that exact address as a Reserved IP. For a VM attached to a VPC, convert its address from the VM's networking settings instead. ### Add a label Optionally enter a **Label** (e.g. `production-web-ip`). The dialog shows the Reserved IP charge for the selected location. ### Reserve Click **Reserve IP** (or **Convert IP**). ## Attach, move, and detach The Reserved IPs list shows each address, its location, what it is attached to, and its status (**Attached** or **Reserved**). Use the row actions or open an address for its detail page. * **Attach to VM** — under **Destination VM and VPC**, select an eligible VM in the same location, then click **Attach IP**. Eligible VMs have their own public network interface (listed as **VM public network (direct)**) or a VPC attachment. * **Move to Another VM** — reassigns an attached address in one step. The current VM loses the address immediately. To move an attached address onto a VM's own public network interface, detach it first and then attach it. * **Detach** — removes the address from its current owner. The address stays reserved for reuse. If a NAT gateway was using it, the gateway receives a replacement address automatically; if a Virtual IP was using it, public ingress to that Virtual IP stops. To use a Reserved IP on a NAT gateway or a Virtual IP, attach it from the VPC's detail page — see [Use a Reserved IP](/docs/network-security/vpc-ip-management#use-a-reserved-ip) and [Virtual IPs](/docs/network-security/vpc-ip-management/virtual-ips). ## Detail page The detail page shows the IPv4 address, type, netmask (`/32`), location, reverse DNS metadata, pricing, the Reserved IP ID, and what the address is attached to. Its **Actions** menu has **Edit Metadata**, **Attach to VM** (or **Move to Another VM**), **Detach**, **Refresh**, and **Release IP**. ## Edit the name and reverse DNS On the address's detail page, click **Actions → Edit Metadata**. You can change the **Name** and **Reverse DNS metadata** (a fully qualified domain name, e.g. `host.example.com`). Editing either field does not change the assigned IPv4 address. > **Warning** > > Reverse DNS is stored as a label only. Saving it does not create or update a > PTR record for the address. ## Release safely Click **Release IP** (or the release action on the list). An attached address cannot be released — detach it first. While a NAT gateway owns the address, release is blocked; change the gateway's address or delete the gateway first. Update any DNS records that still reference the address. Release is permanent and the same address might not be available again. ## Use the API Call `GET /networking/sites?workspace_id=607005` first and copy the exact `site_id` from an entry where `available` is `true`. Do not pass a region name. ```bash curl -X POST \ "https://api.ibee.ai/v1/networking/reserved-ips?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"site_id":"68b99bd78a8eda32ff3f16ea","label":"production-ingress"}' ``` To attach an address, provide the VM ID and, for a VPC resource, its VPC and subnet: ```bash curl -X POST \ "https://api.ibee.ai/v1/networking/reserved-ips/eip-example/attach?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"vm_id":"vm-example","vpc_id":"vpc-example","subnet_id":"subnet-example"}' ``` Use the move operation for an atomic reassignment to another VM. It validates the new VM, VPC, subnet, and site before replacing the old attachment, avoiding the gap caused by a separate detach and attach: ```bash curl -X POST \ "https://api.ibee.ai/v1/networking/reserved-ips/eip-example/move?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"vm_id":"vm-replacement","vpc_id":"vpc-example","subnet_id":"subnet-example"}' ``` Other operations: `GET /networking/reserved-ips` (filter with `site_id`), `GET /networking/reserved-ips/{reserved_ip_id}`, `PATCH /networking/reserved-ips/{reserved_ip_id}` (label and reverse DNS), `POST /networking/reserved-ips/{reserved_ip_id}/detach`, and `DELETE /networking/reserved-ips/{reserved_ip_id}` (release). To give a new NAT gateway a Reserved IP, pass `reserved_public_ip_id` to `POST /networking/vpcs/{vpc_id}/nat-gateways`. **Convert Existing IP**, putting a Reserved IP on an existing NAT gateway, and attaching one to a Virtual IP have no API operation; use the portal. ## Related pages * [VPC & IP management](/docs/network-security/vpc-ip-management) * [Virtual IPs](/docs/network-security/vpc-ip-management/virtual-ips) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [API reference](/docs/api-reference/introduction) --- title: Virtual IPs url: https://ibee.ai/docs/network-security/vpc-ip-management/virtual-ips description: Reserve a specific private IP inside a VPC subnet for MetalLB and Kubernetes LoadBalancer services, announced by nodes you authorize. last_updated: 2026-10-27 --- # Virtual IPs > Reserve a specific private IP inside a VPC subnet for MetalLB and Kubernetes LoadBalancer services, announced by nodes you authorize. A Virtual IP (VIP) is a private address that **you choose** from a VPC subnet and reserve as a floating endpoint. Unlike a VM's private address — which belongs to one VM's interface once the VM attaches to a subnet — a Virtual IP is not bound to any single VM's interface. Instead, you authorize one or more NAT-connected nodes to *announce* it, so traffic for that address is served by whichever announcer is healthy. This is the mechanism behind bare-metal **MetalLB** and **Kubernetes `LoadBalancer`** services: MetalLB advertises the reserved private address from the announcer nodes, giving your service a stable in-VPC IP. > **Info** > > A Virtual IP claims an address for MetalLB and authorizes the nodes that may > announce it. IPAM will not assign the address to a VM, so the same address is > never handed out as a node's interface IP. ## Prerequisites * A VPC with at least one **NAT-connected node** to act as an announcer. Announcers are the VMs that advertise the Virtual IP. * The subnet you want the address to live in (any subnet of the VPC). ## Choose the private IP You pick the exact address. It must be a host address **inside the selected subnet's CIDR** that is currently free. The backend validates the address and rejects it when it is: | Rejected | Reason | | -------------------------------- | -------------------------------------------------------- | | Outside the subnet CIDR | The address must be a host in the chosen subnet's range. | | The subnet gateway | The gateway address is reserved for routing. | | The network or broadcast address | Neither is a usable host address. | | Already allocated | Another node or Virtual IP already holds it. | > **Tip** > > Check the **Private IP ledger** on the VPC's **Subnets** tab, or list the > subnet's existing allocations with > `GET /networking/vpcs/{vpc_id}/network-allocations?workspace_id=607005`, to see > which host addresses are already taken before choosing one. ## Reserve a Virtual IP ### Open Reserved VIPs Open the VPC's detail page and select the **Reserved VIPs** tab, then click **Reserve Virtual IP**. The button is available once the VPC has a subnet. ### Pick a subnet and a free host address Select a **Subnet** and enter the **Private IP** — an unused host address inside its CIDR (for example `10.144.4.17`). ### Choose the announcer nodes Under **MetalLB announcer nodes**, tick the NAT-connected VMs that may announce the address. ### Reserve the address Click **Reserve Virtual IP**. The **Reserved VIPs** tab lists each reservation with its private IP, purpose, announcers, attached public IP, and status. ### Reserve with the API Provide the announcer VM IDs in `announcer_vm_ids`: ```bash curl -X POST \ "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "subnet_id": "subnet-example", "private_ip": "10.144.4.17", "purpose": "metallb", "announcer_vm_ids": ["vm-example-a", "vm-example-b"] }' ``` #### Request fields | Field | Required | Description | | ------------------ | -------- | ----------------------------------------------------------------------------- | | `subnet_id` | Yes | Subnet of the VPC that the address belongs to. | | `private_ip` | Yes | The specific, unused host address to reserve, inside the subnet CIDR. | | `purpose` | Yes | `metallb` for a MetalLB / Kubernetes `LoadBalancer` Virtual IP. | | `announcer_vm_ids` | Yes | One or more VM IDs of NAT-connected nodes authorized to announce the address. | ## List and inspect ```bash # List every Virtual IP in the VPC curl "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" # Inspect a single Virtual IP curl "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips/vip-example?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" ``` Each Virtual IP reports its `private_ip`, `subnet_id`, `purpose`, and the `announcer_vm_ids` currently authorized to advertise it. ## Expose a Virtual IP publicly A Virtual IP is private by design. To make the service it fronts reachable from the internet, attach a [Reserved IP](/docs/network-security/vpc-ip-management/reserved-ips) to it: 1. On the **Reserved VIPs** tab, click **Attach** on the Virtual IP's row. 2. Select an unattached Reserved IP in the VPC's location. 3. Click **Attach Reserved IP**. This creates a one-to-one public mapping: inbound and return traffic use the Reserved IP, while the announcers continue to serve the traffic inside the VPC. To remove public access, click **Detach** on the row and confirm **Detach Reserved IP**. The Virtual IP stays reserved, and the Reserved IP returns to your workspace pool for reuse. On a NAT VPC you can instead forward a single NAT gateway port to the Virtual IP with a [port forwarding rule](/docs/network-security/vpc-ip-management#nat-port-forwarding) (destination type **MetalLB VIP**). ## Release a Virtual IP Releasing a Virtual IP returns the private address to the subnet pool. Remove the address from your MetalLB configuration first. Any Reserved IP attached to it must be detached first — deletion is blocked while one is attached. In the portal, click the delete icon on the Virtual IP's row on the **Reserved VIPs** tab, then click **Delete Reservation**. With the API: ```bash curl -X DELETE \ "https://api.ibee.ai/v1/networking/vpcs/vpc-example/virtual-ips/vip-example?workspace_id=607005" \ -H "Authorization: Bearer $IBEE_TOKEN" ``` ## Errors | Status | When | | ----------------- | ----------------------------------------------------------------------------------------- | | `400 Bad Request` | The address is outside the subnet CIDR, or is the gateway, network, or broadcast address. | | `404 Not Found` | The VPC, subnet, or Virtual IP ID does not exist in this workspace. | | `409 Conflict` | The address is already allocated to another node or Virtual IP. | ## Related pages * [VPC](/docs/network-security/vpc-ip-management) * [Reserved IPs](/docs/network-security/vpc-ip-management/reserved-ips) * [Networking for VMs](/docs/infrastructure/cloud-vms/networking-for-vms) * [API reference](/docs/api-reference/introduction) --- title: VM backups url: https://ibee.ai/docs/tools/backups description: Protect Cloud VMs with scheduled, automated backups of the root disk and attached volumes. last_updated: 2026-10-19 --- # VM backups > Protect Cloud VMs with scheduled, automated backups of the root disk and attached volumes. Backups are scheduled, automated recovery points for Cloud VMs. When enabled on a VM, IBEE captures the root disk and all attached persistent data volumes on a recurring schedule and keeps the resulting **recovery points** so you can restore a VM in place or roll forward to a new VM. If you want a one-off recovery point you trigger manually, use [Snapshots](/docs/tools/snapshots) instead. Backups and snapshots use the same restore flow but differ in cadence: backups run on a schedule, snapshots run on demand. ## What's protected Each backup recovery point captures: * The **root disk** (always included). * **All attached persistent data volumes** at the time the backup runs. The captured topology, total **recovery storage** size, and creation timestamp are visible on each recovery point. ## Where to manage backups Two surfaces in the IBEE Solutions portal: | Surface | Use it for | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Cloud VMs → \ → Backups tab** | Toggle Automated Backups on or off for a VM and pick its schedule. Browse and restore that VM's recovery points. | | **Tools → Backups** | Workspace-wide catalog of backups across your VMs, with per-backup actions. | The **Backups** page (under **Tools → Backups**) lists backups page by page (**Previous** / **Next**) with these columns: | Column | Description | | ---------------------- | ------------------------------------------------- | | **VM / Restore Point** | Source VM name and the restore point's timestamp. | | **OS** | Source VM's operating system. | | **Size** | Backup footprint. | | **Date** | When the backup was taken. | | **Status** | Backup state. | Each row's actions menu offers: * **Convert to Snapshot** — turns the backup into a snapshot, which then appears under [Snapshots](/docs/tools/snapshots). A toast confirms *Conversion started*. * **Delete Backup** — permanently deletes the backup after you confirm with **Delete**. If no VMs in the organization have backups enabled, the page shows an empty state: **No Backups — Automatic backups are an optional service that creates daily snapshots of your VPS instance for a small additional fee. Enable backups on individual servers to see them here.** A **Manage Servers →** button takes you to **Cloud VMs** so you can pick a VM and turn on its schedule. ## Enable backups for a VM Backups are configured per VM under **Backups → Automated Backups**. See [Enable backups](/docs/tools/backups/enable-backups) for the full schedule options. Quick view of the schedule controls: | Field | Options | | -------------------- | ------------------------------------------------------------------------------ | | **Schedule backups** | Daily · Weekly | | **On** (Weekly only) | Sunday · Monday · Tuesday · Wednesday · Thursday · Friday · Saturday | | **At** | Hourly slots — `00:00`, `01:00`, … `23:00` — in your browser's local time zone | Turning backups on starts with a **Daily** schedule at **12:00** in your local time zone. To change it, pick the new values and click **Save Schedule**. Recovery points are kept for **7 days**. ## Recovery points Once at least one backup has run, recovery points appear in the VM's **Recovery Points** list with these columns: | Column | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | **Recovery Point** | The restore point's time and identifier. | | **Topology** | Disks captured (Root + N data disks). | | **Drift** | **In sync**, or **Drifted** when the captured disks differ from the VM's current volumes. | | **Status** | Backup state. | | **Created** | Date and time. | | **Storage** | Recovery storage used. | Each row has **Details** (topology and mount instructions) and **Restore**. To delete a backup, use **Tools → Backups**. Until the first backup runs, the panel reads **No recovery points yet**. ## Restore options When you click **Restore** on a recovery point, three modes are offered: | Mode | Effect | | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Replace Current VM** | Replace the current root disk and recreate the captured data disks in their saved order. | | **Create New VM** | Create a brand-new VM, with new live block volumes, from the recovery point. | | **Restore Selected Disk** | Restore one captured disk as a new detached volume, which you can attach later. The current VM isn't changed. | See [Restore from backup](/docs/tools/backups/restore-from-backup) for full restore steps. ## Remote backup in another data centre If you need copies kept outside the data centre where your VM runs, IBEE offers remote backup to a separate data centre as a managed service. It isn't turned on from the portal: the IBEE team sets it up on request and shares the details and pricing for your setup. Contact [sales@ibee.ai](mailto:sales@ibee.ai) to arrange it. ## Pricing Backup storage is billed separately from the VM. See [Backup pricing](/docs/tools/backups/backup-pricing) for the rate and example calculations. ## Backups vs. snapshots | | Backups | Snapshots | | ------------- | ----------------------------------------------- | ----------------------------------------------- | | Cadence | Daily or Weekly schedule | On demand | | Configuration | Toggle + schedule per VM | Click Create Snapshot | | Capture mode | Root + all attached data volumes | Root only · All attached · Selective | | Restore modes | Replace · Create New VM · Restore Selected Disk | Replace · Create New VM · Restore Selected Disk | | Best for | Continuous protection, DR | Pre-deploy checkpoints, ad-hoc rollback | Most production VMs benefit from **both**: scheduled backups for routine protection, plus a manual snapshot before risky changes. ## Use the API Per-VM backups are in the public API (GPU VMs use the same paths under `/compute/gpu-vms/{vm_id}`): | Task | Operation | | ---------------------------- | --------------------------------------------------------------------------------------------------- | | Read or change the schedule | `GET` / `PATCH /compute/cloud-vms/{vm_id}/backups/policy` | | Turn backups on or off | `POST /compute/cloud-vms/{vm_id}/backups/enable`, `POST /compute/cloud-vms/{vm_id}/backups/disable` | | List recovery points | `GET /compute/cloud-vms/{vm_id}/backups/runs` | | Run a backup now (API only) | `POST /compute/cloud-vms/{vm_id}/backups/runs` | | Move the next run (API only) | `PATCH /compute/cloud-vms/{vm_id}/backups/policy/next-run-at` | | Restore | `POST /compute/cloud-vms/{vm_id}/backups/actions/restore` | Enable and run-now require a `billing_catalog` with the backup storage SKU; no public operation lists that SKU yet. The workspace-wide **Tools → Backups** list, **Delete Backup**, and **Convert to Snapshot** are portal-only. ## Related pages * [Enable backups](/docs/tools/backups/enable-backups) * [Restore from backup](/docs/tools/backups/restore-from-backup) * [Backup pricing](/docs/tools/backups/backup-pricing) * [Snapshots](/docs/tools/snapshots) --- title: Enable backups url: https://ibee.ai/docs/tools/backups/enable-backups description: Turn on automated backups for a Cloud VM and choose a daily or weekly schedule. last_updated: 2026-10-19 --- # Enable backups > Turn on automated backups for a Cloud VM and choose a daily or weekly schedule. Automated backups capture the root disk and all attached persistent data volumes on a schedule. Once enabled, recovery points appear in the **Recovery Points** list and can be restored in place, used to create a new VM, or restored one disk at a time. ## Steps ### 1. Open Backups On the server detail page, open the **Backups** tab. ### 2. Enable Automated Backups Toggle **Automated Backups** to **Enabled**. The first time, backups start right away on a default **Daily** schedule at **12:00** in your browser's local time zone, and the schedule controls become editable. If you turn backups back on later, the VM's previous schedule is reused. Recovery points are kept for **7 days**. ### 3. Pick a frequency Use the **Schedule backups** dropdown: * **Daily** — runs every day at the chosen time. * **Weekly** — runs once per week on the chosen day. ### 4. Pick the day (Weekly only) If you chose **Weekly**, pick a day under **On**: Sunday through Saturday. ### 5. Pick the time Use the **At** dropdown to choose an hourly slot — `00:00`, `01:00`, … `23:00`. Times are in your browser's local time zone, and the schedule is saved with that time zone. Pick a window of low workload activity. Backups run online (the VM stays up) but I/O is briefly busier; pick a time outside peak hours. ### 6. Save the schedule Click **Save Schedule**. The button shows **Saving…** while the change is saved, and a confirmation toast appears when the schedule is active. ## Verify the schedule The fields you saved remain visible at the top of the Backups tab. The next backup runs at the next matching slot — for example, a Weekly + Sunday + 12:00 schedule saved on Tuesday will first run the following Sunday at 12:00 in the time zone it was saved with. The first run produces a recovery point in **Recovery Points**: * Name like `srp-20260509T162709Z` * Disks: `Root + N data disk(s)` * Storage: total recovery footprint (for example `60 GB`) ## Disable backups To stop scheduled backups for a VM, toggle **Automated Backups** to **Disabled**. Existing recovery points are retained according to the retention policy and can still be restored — only the schedule is paused. ## What gets captured Backups always capture: * The root disk. * Every persistent data volume attached at the time the schedule runs. If you attach a new volume midway through a week, it's included starting from the next scheduled run. If you detach a volume before a run, that volume is not in subsequent recovery points. ## Best practices * **Pick a low-traffic window.** The **At** time is in your browser's local time zone — if your servers serve users in another time zone, convert before choosing. * **Use weekly + selective snapshots** if daily storage cost is a concern — cover routine protection with weekly backups, take manual [snapshots](/docs/tools/snapshots) before risky changes. * **Test restore before you need it.** Use **Create New VM** restore mode periodically to confirm your recovery points are usable. * **Keep separate copies of critical data.** Automated backups protect a single VM and live in the same location as the VM; for extra resilience, also copy critical data to [Object Storage](/docs/infrastructure/object-storage). ## Related pages * [VM backups overview](/docs/tools/backups) * [Restore from backup](/docs/tools/backups/restore-from-backup) * [Backup pricing](/docs/tools/backups/backup-pricing) * [Snapshots](/docs/tools/snapshots) --- title: Restore from backup url: https://ibee.ai/docs/tools/backups/restore-from-backup description: Recover a Cloud VM from an automated backup recovery point — in place, into a new VM, or one disk at a time. last_updated: 2026-10-19 --- # Restore from backup > Recover a Cloud VM from an automated backup recovery point — in place, into a new VM, or one disk at a time. Each automated backup creates a recovery point in the VM's **Backups** tab. From there you can replace the existing VM's disks, spin up a new VM from the recovery point, or restore one captured disk as a new volume. The flow is the same dialog as [Snapshot restore](/docs/tools/snapshots/restore-a-snapshot), but **Replace Current VM** and **Restore Selected Disk** behave differently for backups (see below). ## Open the recovery point 1. On the server detail page, open the **Backups** tab. 2. Scroll to **Recovery Points**. 3. Click **Details** on a recovery point to inspect its captured disks, recovery storage, and mount instructions. 4. Click **Restore** to start a recovery. **Restore** is available for successful backups only. ## Recovery Point Details The Details view shows the recovery point's **Disks**, **Storage**, and **Created** time, each captured disk (label, device, size, and its state at capture), and **Mount Instructions** for captured data volumes with a **Copy commands** button. The commands look like this: ```bash sudo mkdir -p /mnt/data sudo mount /dev/vdc /mnt/data echo 'UUID= /mnt/data ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab ``` Don't format (`mkfs`) a restored volume — it already holds your data. ## Restore modes When you click **Restore**, three modes are presented in the side panel. ### Replace Current VM Replace the current VM's root disk and recreate the captured data disks in their saved order. A running VM is briefly stopped, its disks are replaced, and it restarts automatically. Use this when the existing VM is the right target and you want a clean, in-place rollback (for example after a bad deploy). > **Warning** > > **Replacing the current VM overwrites live data.** Anything written after the recovery point is lost. Take a manual [snapshot](/docs/tools/snapshots/create-a-snapshot) of the current state first if you might need it. ### Create New VM Provision a brand-new VM from the recovery point. Set: * **New VM Name** — a name is suggested from the recovery point; edit it if you like. * **New VM Plan** — plans are marked **Eligible**, **Disk too small** (the plan's root disk is smaller than the captured one), or **Unavailable** (not available in this location). * **Restored Data Volume Names** — a name for each captured data disk. The root disk is named from the VM name. New live block volumes are created from each captured disk and auto-attached to the new VM. Use this for non-destructive recovery, migration testing, or cloning a known-good build. ### Restore Selected Disk Restore one captured disk as a **new detached volume**. The current VM isn't changed; attach the volume later from [Block Storage](/docs/infrastructure/block-storage/attach-and-detach-a-volume) if you need it. Pick the disk under **Captured Disk**. The preview confirms it — for example `This will create a new detached volume from testblockstorage (vdc).` ## Restore preview and impact Each mode shows a **Restore Preview** and an amber **Restore Impact** banner: | Mode | Impact | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | Replace Current VM | The current VM is stopped, its root disk is replaced, and captured data disks are attached again. | | Create New VM | A new VM and new live block volumes are created and billed as active resources. | | Restore Selected Disk | The selected disk is restored as a detached volume. You can attach it later without changing the current VM. | Click **Confirm Restore** to start. ## After restore * For **Replace Current VM**, the VM resumes on the same IP with the same hostname. * For **Create New VM**, a new VM appears in the Cloud VMs list with a fresh IP. Update DNS and any callers when you're ready to cut over. * For **Restore Selected Disk**, the new volume appears in **Block Storage**, detached. * Restored data volumes aren't mounted inside the guest automatically. Use the **Mount Instructions** in the recovery point's **Details** view. ## Troubleshooting **Restore is queued but doesn't start** Another operation on the VM may be blocking it. Check [Activity logs](/docs/platform-fundamentals/activity-logs), wait for it to finish, then retry. **New VM has no IP after Create New VM restore** Wait a minute; the IP appears once provisioning completes. If it stays blank, look for a failed create in [Activity logs](/docs/platform-fundamentals/activity-logs). **Data volume isn't visible after restore** The volume is attached but unmounted. Run the **Mount Instructions** from the recovery point's **Details** view inside the guest. ## Related pages * [VM backups overview](/docs/tools/backups) * [Enable backups](/docs/tools/backups/enable-backups) * [Snapshot restore](/docs/tools/snapshots/restore-a-snapshot) * [Block Storage](/docs/infrastructure/block-storage) --- title: Backup pricing url: https://ibee.ai/docs/tools/backups/backup-pricing description: How automated backup storage is billed, sized, and retained on IBEE Solutions. last_updated: 2026-10-19 --- # Backup pricing > How automated backup storage is billed, sized, and retained on IBEE Solutions. Automated backup storage is billed separately from the VM. This page explains how backup size is measured, what you'll see on your bill, and how to keep cost predictable. ## What's billed | Item | Billed? | | -------------------------------------------- | --------------------------------- | | Compute time of the VM the backup belongs to | Yes — billed as the VM's own plan | | Data transfer during backup | No — internal traffic | | Storage occupied by backup recovery points | **Yes — see below** | | Restore operations | No — restores themselves are free | | Network egress from a restored new VM | Yes — billed as VM bandwidth | ## How backup size is measured Each recovery point shows a **Storage** value in the VM's **Backups → Recovery Points** list and in its Details view (for example `60 GB` for a Root + 1 data disk capture). This is the storage footprint of that recovery point. Sizing notes: * The footprint includes the root disk plus every captured data volume. * Backups turned on from the portal are incremental, with a full backup every 7 days. * Empty filesystem space inside disks may be excluded depending on disk format; expect the recovery storage to be roughly the size of used data. ## Retention Backups enabled from the portal keep recovery points for **7 days**. Older recovery points roll off automatically; the retention period can't be changed from the portal. Backups live in the same location as the VM. ## Cost levers you control You can change the storage you're billed for by adjusting: | Lever | Effect | | ---------------------------------------- | ----------------------------------------------------------------------------- | | **Schedule frequency** (Daily vs Weekly) | Daily produces 7× the recovery points per week vs Weekly. | | **Time of day** | No direct cost effect, but off-peak runs reduce I/O contention. | | **Volume layout** | Detaching unused volumes before a run reduces the captured set. | | **Manual cleanup** | Delete backups you no longer need on **Tools → Backups** (**Delete Backup**). | A rough upper bound for the storage you're billed for at any time, with the 7-day retention (incremental points are usually smaller): ``` recovery points kept ≈ 7 (Daily) or 1–2 (Weekly) backup storage ≈ recovery points kept × per-point size ``` For example, a VM with a 60 GB recovery point on a Daily schedule keeps about 7 points — at most roughly 420 GB of backup storage. On a Weekly schedule it keeps 1–2 points — roughly 60–120 GB. ## Verifying current spend Recovery storage rolls up to your account-level usage view. To see per-VM detail: 1. Go to **Cloud VMs → \** → **Backups** tab. 2. The **Recovery Points** list shows each point's **Storage**. 3. Sum the active recovery points to estimate the VM's current backup footprint. ## Reducing backup spend * Move from **Daily** to **Weekly** if your RPO tolerates it. * Detach data volumes you don't need to protect — they stop being captured starting from the next run. * Delete old backups on **Tools → Backups** once you've replaced them with verified snapshots or off-site copies. * Use [Object Storage](/docs/infrastructure/object-storage) for large, append-only data — backing up TB-scale media inside a VM is rarely the right choice. ## Related pages * [VM backups overview](/docs/tools/backups) * [Enable backups](/docs/tools/backups/enable-backups) * [Restore from backup](/docs/tools/backups/restore-from-backup) * [Object Storage pricing](/docs/infrastructure/object-storage/pricing) --- title: VM snapshots url: https://ibee.ai/docs/tools/snapshots description: Capture on-demand recovery points for IBEE Solutions VMs and restore in place or into a new VM. last_updated: 2026-10-19 --- # VM snapshots > Capture on-demand recovery points for IBEE Solutions VMs and restore in place or into a new VM. A **snapshot** is an on-demand recovery point captured from a running Cloud VM. Each snapshot includes the root disk and, optionally, attached data volumes. Snapshots are kept as a **Recovery Point** that you can restore in place, use to create a new VM, or roll back disk-by-disk. Snapshots and [automated backups](/docs/tools/backups) share the same restore flow. Use snapshots when you want a recovery point at a specific moment — before a deploy, OS upgrade, or risky migration. Use backups for continuous, schedule-driven protection. ## What's captured Every snapshot captures the **root disk** by default. You choose how much else to include via **Capture Mode**: | Capture Mode | Captures | | ------------------------ | ----------------------------------------------------------- | | **Root volume only** | Just the boot disk. Attached data volumes are skipped. | | **All attached volumes** | Root disk plus every attached persistent data volume. | | **Selective volumes** | Root is always included; pick specific data volumes to add. | Restoring a snapshot set automatically reattaches captured data volumes to the target VM. Mount instructions for each data volume are surfaced in the Details drawer. ## Restore options When you click **Restore** on a snapshot recovery point, the same three modes are offered as backup restore: | Mode | Effect | | ------------------------- | ----------------------------------------------------------------------------- | | **Replace Current VM** | Roll back the existing VM's root disk and captured data disks in place. | | **Create New VM** | Provision a brand-new VM from the recovery point with new live block volumes. | | **Restore Selected Disk** | Roll back a single captured disk on the current VM. | See [Restore a snapshot](/docs/tools/snapshots/restore-a-snapshot) for full steps. ## When to take a snapshot * Before a **deploy** or migration you might need to roll back. * Before an **OS upgrade** or kernel change. * To **clone a known-good build** into a new VM via the **Create New VM** restore mode. * As a **manual checkpoint** between scheduled backup runs. For routine, ongoing protection, prefer scheduled [automated backups](/docs/tools/backups). ## How often can I take a snapshot? As often as you need — snapshots are taken on demand, at any time. There is no snapshot schedule: take one from the portal, with `ibee vms snapshots create`, or with the API. Snapshots are kept until you delete them. For an automatic daily copy, turn on [automated backups](/docs/tools/backups) instead. Backups run on a **Daily** or **Weekly** schedule and keep **7 days** of recovery points. ## Where to manage snapshots Two surfaces in the IBEE Solutions portal manage snapshots: | Surface | Use it for | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cloud VMs → \ → Snapshots tab** | Rich per-VM flow: pick a Capture Mode (Root only / All attached / Selective), browse Recovery Points, and restore in three modes (Replace · Create New VM · Restore Selected Disk). | | **Tools → Snapshots** | Workspace-wide catalog of recovery points and point-in-time copies across your VMs, with a **Take Snapshot** button. | The Tools page is the aggregate view. A search box filters by snapshot, VM, volume, or ID, and the list is paginated. Each row shows: | Column | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------ | | **Snapshot** | Snapshot name and a short identifier (with a copy button). | | **Disks** | What was captured (for example `Root volume · 1 disk`). | | **Storage** | Snapshot footprint. | | **Status** | `Available` once the snapshot is ready; in-progress states such as `Creating` or `Pending` while it's being taken. | | **Created** | Date and time. | | **Action** | Row menu with **Manage snapshot**, which opens the snapshot's details. | **Manage snapshot** shows the snapshot's name, type (recovery point or volume snapshot), snapshot ID, source VM, source volume, disks, capture mode, storage, status, created/updated times, and description — plus **Delete Snapshot**. Restores are started from the VM's **Snapshots** tab. **Take Snapshot** on the Tools page opens a dialog with: * **Virtual Machine** — pick a VM. * **Snapshot Name** — required. * **Description** — optional note for this restore point. * **Capture Mode** — **Root volume only**, **All attached volumes**, or **Selective volumes** (tick the data volumes to include). If the VM has no attached data volumes, the snapshot is root-only. * A reminder to run `sync` inside the VM to flush pending writes before taking the snapshot. Both surfaces offer the same capture modes. Use the per-VM **Snapshots** tab when you also want to browse recovery points and restore. ## Quick start 1. Open the VM detail page → **Snapshots** tab. 2. Enter a **Label** (required) and an optional **Description**. 3. Pick a **Capture Mode** — Root only, All attached, or Selective. 4. (Selective only) Tick the data volumes to include. 5. Click **Create Snapshot**. The recovery point appears in the **Recovery Points** list when complete. See [Create a snapshot](/docs/tools/snapshots/create-a-snapshot) for the full flow. ## Recovery point list Each row shows: * **Snapshot** — your label and the system-generated identifier (for example `srp-20260509T162709Z`). * **Disks** — what's captured (`Root + 1 data disk`, `2 disk(s)`, …). * **Created** — date and time. * **Storage** — total recovery footprint. * **Actions** — **Details**, **Restore**, **Delete**. ## Snapshots vs. backups | | Snapshots | Backups | | ------------- | ------------------------------------------------ | -------------------------------------- | | Cadence | On demand | Daily or Weekly schedule | | Trigger | Manual click | Automatic | | Capture mode | Root only · All attached · Selective | All attached (root + all data volumes) | | Restore modes | Replace · Create New VM · Restore Selected Disk | Same | | Best for | Pre-deploy checkpoints, ad-hoc rollback, cloning | Continuous protection, DR | Most production VMs use both: scheduled backups as the safety net, manual snapshots before risky changes. ## Use the API Per-VM snapshots are in the public API (GPU VMs use `/compute/gpu-vms/{vm_id}/snapshots` and `/compute/gpu-vm-snapshots/...`): | Task | Operation | | ------------------------ | -------------------------------------------------------------------- | | Create a snapshot | `POST /compute/cloud-vms/{vm_id}/snapshots` | | List a VM's snapshots | `GET /compute/cloud-vms/{vm_id}/snapshots` | | Get or delete a snapshot | `GET` / `DELETE /compute/cloud-vm-snapshots/{snapshot_set_id}` | | Restore | `POST /compute/cloud-vm-snapshots/{snapshot_set_id}/actions/restore` | Create requires a `billing_catalog` with the snapshot storage SKU; no public operation lists that SKU yet. The workspace-wide list on **Tools → Snapshots** is portal-only. ## Related pages * [Create a snapshot](/docs/tools/snapshots/create-a-snapshot) * [Restore a snapshot](/docs/tools/snapshots/restore-a-snapshot) * [VM backups](/docs/tools/backups) --- title: Create a snapshot url: https://ibee.ai/docs/tools/snapshots/create-a-snapshot description: Capture a manual recovery point of a Cloud VM — root disk plus optional data volumes. last_updated: 2026-10-19 --- # Create a snapshot > Capture a manual recovery point of a Cloud VM — root disk plus optional data volumes. Manual snapshots produce an on-demand **Recovery Point** for a Cloud VM. They include the root disk and, optionally, attached data volumes. Use snapshots before risky changes, or as a clone source for new VMs via [restore](/docs/tools/snapshots/restore-a-snapshot). ## Steps ### 1. Open Snapshots On the server detail page, open the **Snapshots** tab. The first time you visit, an info banner reminds you that **restoring a snapshot will stop the server briefly, roll back the disk, and start it again automatically.** ### 2. Add a label and (optional) description Under **Create Snapshot**: * **Label** (required) — short, human-readable name. Example: `pre-deploy-2026-05-09`. * **Description** (optional) — context like the change you're about to make. Example: `Snapshot before upgrading Postgres to 17`. Use clear, dated labels. Recovery points are also tagged with a system-generated identifier (`srp-20260509T162709Z`) but the label is what you'll see first in the list. ### 3. Pick a Capture Mode Three modes are offered. Root volume is always captured; the mode controls what else is included. | Mode | Capture | | ------------------------ | -------------------------------------------------------------------------- | | **Root volume only** | Boot disk only. Attached data volumes are skipped. | | **All attached volumes** | Root disk plus every attached persistent data volume. | | **Selective volumes** | Root plus the data volumes you tick from the **Select Data Volumes** list. | A green confirmation banner — **Root volume is always included** — appears regardless of mode. ### 4. (Selective only) Pick data volumes For **Selective volumes**, the **Select Data Volumes** list appears with each attached volume's: * Label (for example `testblockstorage`) * Size and device path (for example `10 GB · vdc · /mnt/volume_`) Tick the boxes for the volumes to include. The header shows a running count (`1 selected`, `2 selected`, …). ### 5. Create the snapshot Click **Create Snapshot** in the bottom-right of the form. The platform briefly captures the disks and produces a recovery point. A success toast — **Snapshot set created** — confirms the operation. The new entry appears in **Recovery Points**. ## What you get Each recovery point shows: * **Snapshot** — your label, plus the system identifier (`srp-`). * **Disks** — what was captured (`Root + 1 data disk`, etc.) with the provisioned disk size displayed for each volume. * **Created** — date and time. * **Storage** — total recovery storage used (provisioned size, not compressed size). * **Actions** — **Details**, **Restore**, **Delete**. Click **Details** to inspect the captured disks (root vs. data, target devices, filesystem types, and disk sizes) and copy mount instructions for any data volumes. ## Capture mode tips * **Root volume only** is the fastest and smallest. Use when you're protecting only the OS install. * **All attached volumes** is the safest default for production. Use when data and root must be recoverable together. * **Selective volumes** is useful when one volume holds large, unimportant data (build cache, temp files) and you want to skip it. ## Best practices * Use **descriptive, dated labels** so you can find the right recovery point later. * **Quiesce the workload** if you need a transactionally consistent snapshot — flush database buffers (`pg_start_backup`, `FLUSH TABLES WITH READ LOCK`) before snapshotting, or stop the application briefly. * **Test restore periodically** with **Create New VM** to confirm your snapshots are usable. * **Delete old snapshots** you no longer need — recovery storage is billed. ## Verify Switch to the **Recovery Points** section at the bottom of the Snapshots tab. The new row should match your label and show **Storage** (provisioned disk size) and **Created** values. If it shows `Loading snapshots…` or `No snapshots yet`, refresh after a few seconds. ## Troubleshooting **Create button is disabled** Enter a label — it's required. **Snapshot stuck in progress** Check [Activity logs](/docs/platform-fundamentals/activity-logs) for a failed snapshot and its reason. **Selective volumes list is empty** The VM has no attached data volumes. Either switch to **Root volume only** or attach a [block storage volume](/docs/infrastructure/cloud-vms/attach-volumes) first. ## Related pages * [VM snapshots overview](/docs/tools/snapshots) * [Restore a snapshot](/docs/tools/snapshots/restore-a-snapshot) * [Attach volumes](/docs/infrastructure/cloud-vms/attach-volumes) * [VM backups](/docs/tools/backups) --- title: Restore a snapshot url: https://ibee.ai/docs/tools/snapshots/restore-a-snapshot description: Roll back a Cloud VM, create a new VM, or restore a single disk from a snapshot recovery point. last_updated: 2026-10-19 --- # Restore a snapshot > Roll back a Cloud VM, create a new VM, or restore a single disk from a snapshot recovery point. Each snapshot creates a **Recovery Point** in the VM's **Snapshots** tab. From there you can roll back the existing VM, spin up a new VM from the recovery point, or restore one captured disk in place. [Automated backups](/docs/tools/backups/restore-from-backup) use the same restore dialog, with small differences for backups. > **Warning** > > **Restoring a snapshot stops the server briefly.** The platform rolls back the disk and starts the VM again automatically. Connections in flight will be interrupted. ## Open the recovery point 1. On the server detail page, open the **Snapshots** tab. 2. Scroll to **Recovery Points**. 3. Click **Details** to inspect captured disks and mount instructions. 4. Click **Restore** to start the recovery flow. ## Recovery Point Details The Details view shows the recovery point's **Disks**, **Storage**, and **Created** time, each captured disk (label, device, size, and its state at capture), and **Mount Instructions** for captured data volumes with a **Copy commands** button. The commands look like this: ```bash sudo mkdir -p /mnt/data sudo mount /dev/vdc /mnt/data echo 'UUID= /mnt/data ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab ``` Don't format (`mkfs`) a restored volume — it already holds your data. ## Restore modes When you click **Restore**, a side panel appears with the snapshot summary (Recovery Point ID, captured disks, topology, VM disk size, protected size) and three modes. ### Replace Current VM Roll back the current VM's root disk and all captured data disks in place. The VM is briefly stopped, disks are replaced, and it restarts automatically. Use when the existing VM is the right target and you want a clean rollback (e.g. after a bad deploy). > **Restore Impact:** The current VM will be stopped, its root disk will be replaced, and captured data disks will be attached again. ### Create New VM Provision a brand-new VM from the recovery point. Set the **New VM Name** (a name is suggested), pick a **New VM Plan** (plans are marked **Eligible**, **Disk too small**, or **Unavailable**), and name each disk under **Restored Data Volume Names**. New live block volumes are created from each captured disk and auto-attached to the new VM. > **Restore Impact:** A new VM and new live block volumes will be created from this recovery point and billed as active resources. The **Restore Preview** lists each disk that will appear on the new VM with its target device and original mount path: ``` vmroot-test-clone · vda · / testblockstorage · vdc · /mnt/volume_ ``` Use this for non-destructive recovery, migration testing, or cloning a known-good build. ### Restore Selected Disk Roll back a single captured disk in place on the current VM. Useful when only one volume is corrupted and you don't want to disturb the rest. Pick the disk to restore from the **Captured Disk** dropdown. The preview confirms the change, e.g. `This will roll back vmroot-test-clone (vda) in place.` > **Restore Impact:** The selected disk will be rolled back in place. The VM may be briefly stopped and started again automatically. ## Confirm and run Click **Confirm Restore** at the bottom of the side panel. The platform runs the restore; you can follow it in [Activity logs](/docs/platform-fundamentals/activity-logs). ## After restore | Mode | Resulting state | | --------------------- | ---------------------------------------------------------------------------------------- | | Replace Current VM | VM resumes on the same IP and hostname with rolled-back disks. | | Create New VM | New VM appears in the list with a fresh IP. Update DNS / callers when ready to cut over. | | Restore Selected Disk | VM resumes with the selected disk rolled back; other disks untouched. | For both Replace and Create New VM, captured **data volumes** are auto-attached but **not auto-mounted** inside the guest. Run the **Mount Instructions** from the recovery point's **Details** view. ## Troubleshooting **Restore is queued but doesn't start** Another operation on the VM may be blocking it. Check [Activity logs](/docs/platform-fundamentals/activity-logs), wait for it to finish, then retry. **New VM has no IP after Create New VM** Wait a minute; provisioning takes longer than a regular deploy because disks are being copied. If the IP stays blank, look for a failed create in Activity logs. **Data volume isn't visible after restore** The volume is attached but unmounted. Run the **Mount Instructions** from the recovery point's **Details** view. **Wrong disk restored** Take a snapshot of the current state first, then redo the restore against the correct disk. Avoid restore-followed-by-restore on the same disk without a snapshot in between. ## Related pages * [VM snapshots overview](/docs/tools/snapshots) * [Create a snapshot](/docs/tools/snapshots/create-a-snapshot) * [Restore from backup](/docs/tools/backups/restore-from-backup) * [Attach volumes](/docs/infrastructure/cloud-vms/attach-volumes) --- title: ISOs url: https://ibee.ai/docs/tools/isos description: Add custom ISO images to your IBEE Solutions organization from a remote URL, attach them to VMs, and choose them when deploying. last_updated: 2026-10-19 --- # ISOs > Add custom ISO images to your IBEE Solutions organization from a remote URL, attach them to VMs, and choose them when deploying. ISOs let you bring operating system installers and other boot images that aren't in the [OS template catalog](/docs/infrastructure/cloud-vms/os-images). Add an ISO once from a remote URL, then choose it under **Operating System → ISOs** when [creating a VM](/docs/infrastructure/cloud-vms/create-a-vm), or attach it to an existing VM from the ISOs page. > **Warning** > > **Interactive installs need a console, which isn't available in the portal yet.** A VM booted from an installer ISO waits for you to step through the installer, and browser console access is still **Coming soon**. You can add, attach, and detach ISOs today, but plan on a [template](/docs/infrastructure/cloud-vms/os-images) or a [snapshot](/docs/tools/snapshots) for VMs you need to reach now. ## Open the ISOs page 1. In the IBEE Solutions portal, expand **Tools** in the left nav. 2. Click **ISOs**. The page lists every ISO in the current organization, with a **Search ISOs…** box (matches the ISO name) and a **Refresh** button. The empty state shows **No ISOs Found** with an **Add ISO** call-to-action. The list has these columns: | Column | What it shows | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **ISO** | The name you gave the ISO. | | **Status** | **Pending** while IBEE downloads and validates the image, **Complete** when it's ready to use, or **Error** if the download or validation failed. | | **Size** | The image size once downloaded. | | **MD5** | The image checksum, so you can compare it with the publisher's value. | | **Attached To** | The VM the ISO is attached to, or **Not attached**. | | **Added** | When the ISO was added. | ## Add an ISO ### 1. Click Add ISO Click **Add ISO** (top-right or the empty-state button). The **Add ISO** dialog opens with the subtitle **Upload from a remote URL (up to 10 GB)**. ### 2. Enter a name In **ISO Name**, give the image a clear, human-readable label. Example: `Ubuntu 24.04 LTS` This is the name you'll see in the ISOs list and in the VM deployer's **ISOs** tab. ### 3. Paste a remote URL In **Remote URL**, paste the public URL where the ISO can be downloaded. Example: `https://releases.ubuntu.com/24.04/ubuntu-24.04.iso` ### 4. Confirm the constraints The dialog reminds you of the upload requirements: | Constraint | Value | | ------------------------------------------- | ----------------------------------------------- | | ISO must be publicly accessible via the URL | Yes — IBEE pulls from the URL you provide | | Supported formats | `.iso` images only | | Maximum size | **10 GB** | | URL scheme | Must begin with **`http://`** or **`https://`** | If your image lives behind authentication, host it on a public bucket (such as [Object Storage](/docs/infrastructure/object-storage)) or generate a signed URL that doesn't require headers. ### 5. Click Add ISO Click **Add ISO** in the bottom-right of the dialog. A confirmation reads **ISO added — validating URL in background…**, and the new entry appears with status **Pending**. It changes to **Complete** once IBEE has downloaded and validated the image. Click **Refresh** to update the list. ## Attach an ISO to a VM You can attach a **Complete** ISO that isn't attached anywhere to an existing VM: 1. On the ISO's row, open the actions menu and click **Attach**. 2. In the **Attach ISO** dialog, enter the **VM ID**. **VM Name** is optional and is used as a label. 3. Click **Attach**. The **Attached To** column then shows the VM. Each ISO can be attached to one VM at a time. Attaching records the VM against the ISO on this page; it doesn't change how an existing VM boots. To boot from an ISO, deploy a new VM from it (below). ## Detach an ISO 1. On the attached ISO's row, open the actions menu and click **Detach**. 2. The **Detach ISO** dialog shows which VM it's **Currently attached to**. Confirm with **Detach**. ## Boot a new VM from your ISO 1. Open **Infrastructure → Cloud VMs** and click **Deploy VM**. 2. Pick the **Location** and **Plan** as usual. 3. Under **Operating System**, switch to the **ISOs** tab. 4. Pick your ISO from the list. 5. Continue with **SSH Keys**, **Network Configuration**, **Billing**, and **VM Details**, then click **Deploy**. The VM boots from the ISO. Completing an interactive installer requires console access, which isn't available in the portal yet — see the note at the top of this page. ## Manage ISOs From the ISOs list: * Use the **search box** to filter by name. * Use **Refresh** to re-poll the list after a recent upload. * Use the per-row actions menu to **Attach**, **Detach**, or **Delete** an ISO. **Delete** is disabled while the ISO is attached — the dialog shows **Detach from VM first before deleting.** Deleting an ISO removes it from organization storage. VMs already installed from the ISO are unaffected — the install lives on the VM's own root disk. ## Bring-your-own-image checklist For a custom Linux ISO to boot cleanly under KVM, verify before uploading: * **virtio drivers** for disk and network are present (Linux kernels include them by default). * **DHCP client** is enabled on the primary NIC. * The ISO has a working **bootloader** that targets `/dev/vda`. * (Optional) Install **cloud-init** during the install for SSH key injection on next boot. For Windows ISOs, plan to install virtio drivers from the [Windows guest tools ISO](https://github.com/virtio-win/kvm-guest-drivers-windows) during setup. ## Troubleshooting **Add ISO button is disabled** Both **ISO Name** and **Remote URL** are required. If the URL doesn't start with `http://` or `https://`, the dialog shows an error when you click **Add ISO**. **Status stays Pending or changes to Error** The URL must be publicly reachable from IBEE infrastructure. Check the URL in a browser; if it requires authentication, redirects to a login page, or rate-limits unauthenticated downloads, host the ISO somewhere that doesn't. Then delete the failed entry and add the ISO again. **Image rejected as "unsupported format"** Only `.iso` files are accepted. Cloud images in `.qcow2`, `.img`, or `.vmdk` are not — for those, see [Custom images](/docs/infrastructure/cloud-vms/custom-images) (snapshot/backup paths instead). **Attach is missing from the row menu** **Attach** appears only for ISOs with status **Complete** that aren't already attached. Detach the ISO from its current VM first. **Can't delete an ISO** Detach it from its VM first. ## Related pages * [OS images](/docs/infrastructure/cloud-vms/os-images) * [Custom images](/docs/infrastructure/cloud-vms/custom-images) * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) --- title: SSH Keys url: https://ibee.ai/docs/tools/ssh-keys description: Create or import SSH keys in an IBEE Solutions workspace so you can log in to your VMs without a password. last_updated: 2026-10-19 --- # SSH Keys > Create or import SSH keys in an IBEE Solutions workspace so you can log in to your VMs without a password. SSH keys let you log in to your VMs securely without a password. Save a key once in a workspace, then select it when you deploy a VM in that workspace — the public key is added to the VM at first boot. SSH keys belong to a **workspace**. A key saved in one workspace is not available in another; save it in each workspace where you deploy VMs. ## Before you begin * A workspace in an active organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)) * Write access to the workspace — members with read-only access can view keys but cannot add or delete them ## Open SSH Keys In the portal sidebar, click **SSH Keys** under **Tools**. The page lists the keys saved in the current workspace. You have two ways to add a key: | Option | Use it when | | ------------------- | --------------------------------------------------------------------------------------------------- | | **Create Key Pair** | You don't have a key yet. IBEE generates a new key pair and your browser downloads the private key. | | **Import Key** | You already have a key pair on your computer and want to add its public key. | ## Create a key pair ### Start On **SSH Keys**, click **Create Key Pair**. ### Name the key Enter a **Key Pair Name** (for example `my-laptop-key`) and, optionally, a **Description**. Names must be unique within the workspace. ### Create and download Click **Create & Download**. Your browser downloads the private key as a `.pem` file named after the key. > **Warning** > > The private key is downloaded **only once**. IBEE stores only the public key and cannot show or re-send the private key. Keep the `.pem` file safe — if you lose it, create a new key pair. Before using the downloaded key, restrict its permissions: ```bash chmod 600 ~/Downloads/my-laptop-key.pem ``` ## Import an existing public key If you don't have a key pair yet and prefer to create one locally, generate it first: ```bash # ed25519 (recommended) ssh-keygen -t ed25519 -C "your-email@example.com" # or RSA ssh-keygen -t rsa -b 4096 -C "your-email@example.com" ``` Your public key is at `~/.ssh/id_ed25519.pub` (or `~/.ssh/id_rsa.pub`). ### Start On **SSH Keys**, click **Import Key**. ### Name the key Enter a **Key Pair Name** and, optionally, a **Description**. ### Add the public key Paste the key into **Public Key**, or click **Choose public key file** to upload it. The portal accepts a one-line OpenSSH public key (such as `ssh-ed25519 …`, `ssh-rsa …`, or `ecdsa-sha2-nistp256 …`) or a PEM file containing a public key. Files must be smaller than 64 KB. ### Import Click **Import Key**. The key appears in the list. ## SSH keys list | Column | Description | | --------------- | ------------------------------------------------- | | **Name** | Key name | | **Key Type** | Algorithm, for example `ssh-ed25519` or `ssh-rsa` | | **Fingerprint** | Fingerprint for verifying the key | | **Created At** | Date the key was added | | **Actions** | **View** · **Delete** | Click **View** to open **SSH Key Details**, where you can copy the fingerprint and the full public key. ## Delete a key Click **Delete** in the **Actions** column, then **Delete Key** to confirm. Deleting a key removes it from the workspace, so it can no longer be selected for new VMs. The portal warns that servers using the key will stop accepting it. To be certain access is revoked on a running VM, remove the key from the VM under **Settings → Access**, or delete it from `~/.ssh/authorized_keys` on the VM. ## Use a key when deploying a VM In the VM deploy form, select one or more saved keys in the **SSH Keys** section, or click **Add Key** to create or import one without leaving the form. The SSH Keys section is not shown for Windows images. See [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm). ## Change access on an existing VM On a Linux Cloud or GPU VM, open the VM and go to **Settings → Access** (**Secure Shell Access**). The VM must be running, and you need write access. * **SSH Keys** — lists the keys installed on the VM. To add one, pick a saved key under **Select SSH key** and click **Add Key**; tick **Disable password login after adding this key** to switch to key-only login at the same time. Click **Remove** to take a key off the VM. If password login is off, removing the last key asks you to confirm with **Remove key**, because you may lose access. * **Password Login** — shows **Enabled** or **Disabled**. Click **Enable** or **Disable**. You can disable it only while the VM has at least one SSH key. * **Reset Password** — enter the new password twice (at least 8 characters) and click **Reset Password**. Windows VMs show **Windows Access** instead: connect with Remote Desktop and manage users and passwords inside Windows. The API operation is `PATCH /compute/cloud-vms/{vm_id}/actions/access` (GPU VMs: `/compute/gpu-vms/{vm_id}/actions/access`). It takes inline public keys in `ssh_keys` with `ssh_key_mode` `add` or `remove`, `new_password`, and `password_auth_enabled`. Saved SSH keys have no public API; send public keys inline (`ssh_keys`) when you create or change a VM through the API. ## Connect to a VM Find the VM's IP address and login user under **Overview → Connection Details**, then connect with the matching private key: ```bash # Key pair created in the portal ssh -i ~/Downloads/my-laptop-key.pem @ # Imported key ssh -i ~/.ssh/id_ed25519 @ ``` ## Troubleshooting **"Private key files cannot be imported."** You pasted or uploaded the private key. Import the **public** key instead — the `.pub` file, or a PEM file that contains `PUBLIC KEY`. **"A key with this name already exists."** Key names must be unique in the workspace. Choose a different name. **I can't see my key when deploying a VM.** Keys belong to a workspace. Check that you are deploying in the same workspace where the key is saved, or import the key into this workspace. **Permission denied (publickey) when connecting** * Check that you are using the private key that matches a key selected for the VM, with `-i`. * Check the login user shown under **Overview → Connection Details**. * If you used a downloaded `.pem` file, run `chmod 600` on it. * Make sure the VM is running and its firewall group allows SSH (TCP 22) from your IP address. **The `.pem` file didn't download or was lost.** The private key can't be downloaded again. Delete the key and create a new key pair, then add the new key to your VMs under **Settings → Access**. ## Related pages * [Create a VM](/docs/infrastructure/cloud-vms/create-a-vm) * [Launch your first VM](/docs/infrastructure/cloud-vms/launch-your-first-vm) * [API Tokens](/docs/tools/api-tokens) --- title: API Tokens url: https://ibee.ai/docs/tools/api-tokens description: Create and manage organization-level API tokens for the IBEE public API, scoped to the entire organization or specific workspaces, and S3 credentials for Object Storage. last_updated: 2026-10-27 --- # API Tokens > Create and manage organization-level API tokens for the IBEE public API, scoped to the entire organization or specific workspaces, and S3 credentials for Object Storage. API tokens give you programmatic access to IBEE Solutions services. Tokens are managed at the **organization level**: in the portal sidebar, click **API Tokens** under **Organization**. Only organization **Admins** can see and manage this page. The page has these tabs: | Tab | What you create there | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API Tokens** | Bearer tokens for the IBEE REST API, CLI, and SDKs — scoped to the **Entire Organization** or **Specific Workspaces** | | **S3 Credentials** | Access Key ID and Secret Access Key for one workspace's Object Storage, for S3-compatible tools | | **Registry access tokens** | Tokens for Docker and OCI clients to access a container registry | | **Email Tokens** | Send-only tokens for one verified sending domain. Shown only when Email Service is enabled for your organization. See [Email Service](/docs/tools/email-service#create-an-api-key). | This page covers **API Tokens** and **S3 Credentials**. ## Before you begin * An active IBEE Solutions organization ([Create an organization](/docs/getting-started/account-setup/create-an-organization)) * A verified identity ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)) > **Info** > > Identity verification is required to create API tokens. If you haven't verified, the **Create API Token** button shows **Verify Identity** and redirects to the verification page. ## Create a token ### Go to API Tokens In the organization sidebar, click **API Tokens** under **Organization**. ### Open the create dialog On the **API Tokens** tab, click **Create API Token**. For S3 credentials, open the **S3 Credentials** tab and click **Create S3 Credential** instead. ### Enter a name | Field | Required | Description | | ----- | -------- | ----------------------------------------------------------------------- | | Name | Yes | Identifies the token (max 100 characters), e.g. "Production automation" | ### Choose an access policy For a platform token, select **Entire Organization** or **Specific Workspaces** from the **Access policy** dropdown. #### Entire Organization The token has access to **all workspaces** in the organization. Choose this for organization-wide API automation. Under **Permissions**, set access for each product: | Product | Covers | API scopes (Read / Edit) | | -------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- | | **Virtual Machines** | Cloud and GPU virtual machines | `vm.read` / `vm.write` | | **Object Storage** | Object Storage | `object-storage.read` / `object-storage.write`, `object-storage.delete` | | **Block Storage** | Volumes, attachments, resizing, and volume operations | `block-storage.read` / `block-storage.write` | | **CDN** | CDN distributions, cache purge, websites, and custom domains | `cdn.read` / `cdn.write` | | **Networking** | VPCs, subnets, NAT gateways, and reserved IPs | `network.read` / `network.write` | | **Firewall** | Firewall groups and rules | `firewall.read` / `firewall.write` | | **Load Balancer** | Load balancers | `load-balancer.read` / `load-balancer.write` | | **Secret Manager** | Secret Manager | `secret-store.read` / `secret-store.write` | | **Billing** | Billing information | `billing.read` (read only) | Select **Read** and/or **Edit** for each product. At least one permission must be selected. Platform tokens cannot be scoped to Email Service, Container Registry, team, activity, or support. Set a **Token expiration**: No expiration, 7 days, 30 days, 90 days, or 1 year. #### Specific Workspaces The token is scoped to **selected workspaces** only. After choosing this policy, a workspace selector appears — pick one or more workspaces. Permissions and expiration options are the same as Entire Organization, but the token only works within the selected workspaces. #### S3 credentials **Create S3 Credential** on the **S3 Credentials** tab creates **S3-compatible credentials** (Access Key ID + Secret Access Key) for one workspace's Object Storage. Use them with AWS CLI, rclone, or any S3-compatible client. 1. **Select a workspace** (required) — the workspace whose Object Storage this credential accesses. 2. **Choose a permission level:** | Permission | What it allows | | ----------------------- | -------------------------------------------------------------------------------------- | | **Admin Read & Write** | Create, list, delete buckets; edit bucket configuration; read, write, and list objects | | **Admin Read only** | List buckets; view configuration; read and list objects | | **Object Read & Write** | Read, write, and list objects in selected buckets | | **Object Read only** | Read and list objects in selected buckets | 3. **Specify bucket scope** (for Object Read & Write / Object Read only): * **Apply to all buckets in the selected workspace** (including newly created buckets) * **Apply to specific buckets only** — a bucket selector appears to pick individual buckets ### Create the token Click **Create API Token** (for platform tokens) or **Create Credential** (for S3). ### Save your credentials After creation, credentials are displayed once. Copy them immediately. #### Platform tokens (Entire Organization / Specific Workspaces) | Credential | Format | Use | | ------------ | ------------- | -------------------------------------------- | | Bearer Token | `ibee_v4_...` | `Authorization` header for the IBEE REST API | #### S3 credentials | Credential | Format | Use | | ----------------- | ------------------------------------------- | ---------------------------------------------------------- | | Access Key ID | `AKIA...` | S3 credential for AWS CLI, rclone, and S3-compatible tools | | Secret Access Key | Shown once only | S3 credential — copy immediately | | S3 Endpoint | `https://WORKSPACE-ID.blob.ibeestorage.com` | S3-compatible endpoint URL for the workspace | > **Warning** > > **Copy your credentials now.** The Secret Access Key and Bearer Token are not shown again. If you lose them, revoke the token and create a new one. ## Manage tokens The **API Tokens** tab lists platform tokens. The **S3 Credentials** tab lists S3 credentials, with a workspace filter. Each row shows: | Column | Description | | --------------- | ------------------------------------------------------------------- | | **Name** | Token name and the last characters of the token | | **Access** | The whole organization, or the workspaces the token can use | | **Permissions** | The products the token can use, or the S3 permission level | | **Created** | Creation date | | **Last Used** | When the token was last used | | **Status** | **Active** or **Revoked** | | **Actions** | **Revoke** for active tokens; **Delete** for revoked S3 credentials | ## Revoke a token Click **Revoke** in the Actions column. Revoked tokens lose access immediately and cannot be restored. A revoked platform token stays in the list with **No further action**. Create a new token if access is needed again. ## Use S3 credentials with tools ### AWS CLI ```bash aws configure set aws_access_key_id YOUR-ACCESS-KEY-ID aws configure set aws_secret_access_key YOUR-SECRET-ACCESS-KEY aws configure set default.region us-east-1 # List buckets aws s3 ls --endpoint-url https://WORKSPACE-ID.blob.ibeestorage.com ``` ### rclone ```ini [ibee] type = s3 provider = Other access_key_id = YOUR-ACCESS-KEY-ID secret_access_key = YOUR-SECRET-ACCESS-KEY endpoint = https://WORKSPACE-ID.blob.ibeestorage.com ``` ## Troubleshooting **Create API Token button shows "Verify Identity"** Complete [identity verification](/docs/getting-started/account-setup/verify-your-identity) before creating tokens. **Create button is disabled** At least one permission must be selected. For Specific Workspaces, select at least one workspace. For S3, select a workspace. **Secret Access Key not saved** The Secret Access Key is shown once only. Revoke the credential and create a new one. **S3 authentication failing** Verify you are using: * The correct **S3 Endpoint**: `https://WORKSPACE-ID.blob.ibeestorage.com` * The **Access Key ID** and **Secret Access Key** from the same credential ## Related pages * [Object Storage API Credentials](/docs/infrastructure/object-storage/api-tokens) * [Create a bucket](/docs/infrastructure/object-storage/buckets) * [Permissions and policies](/docs/infrastructure/object-storage/buckets/bucket-policies) --- title: Secret Manager url: https://ibee.ai/docs/tools/secret-manager description: Store API keys, passwords, and other sensitive values in IBEE Solutions Secret Manager — versioned secrets grouped in stores, with AppRole and Kubernetes access for your apps. last_updated: 2026-10-27 --- # Secret Manager > Store API keys, passwords, and other sensitive values in IBEE Solutions Secret Manager — versioned secrets grouped in stores, with AppRole and Kubernetes access for your apps. Secret Manager keeps sensitive values — API keys, database passwords, tokens — out of your code and config files. Secrets live in **stores**, every update creates a new **version** you can roll back to, and applications read secrets through scoped **access identities** instead of sharing human credentials. ## Concepts | Concept | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Store** | A container for related secrets and the identities that can use them. Its **store key** is auto-generated from the name. | | **Secret** | A named set of key/value entries (e.g. `API_KEY`, `DB_PASSWORD`) inside a store. Updates create new versions. | | **Access** | A machine identity — **AppRole** for VMs, servers, and scripts, or **Kubernetes** for pods and service accounts — with **Read only** or **Read & write** permission. | ## Before you begin * A verified IBEE Solutions organization — Secret Manager actions require identity verification ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)) ## Create a store ### Open Secret Manager In the portal sidebar, click **Secret Manager** under **Tools**. ### Create the store Click **Create Store** and fill in: * **Store name** — e.g. `Payments`. The store key is auto-generated from the name. * **Description** — optional. The store appears in the list with its name, store key, status, and last-updated time. Click it to open the detail view with two tabs: **Secrets** and **Access**. ## Create a secret On the store's **Secrets** tab, click **Create Secret**: * **Secret name** — lowercase, e.g. `stripe-api`. * **Keys and values** — one or more entries (e.g. `API_KEY` = `sk_live_...`). Click **+ Add another key** for more. Row actions on each secret: | Action | What it does | | ----------- | --------------------------------------------------------------------------- | | **View** | Reveals the current version's key/values as JSON, with **Copy JSON** | | **Update** | Edit the key/values and **Save new version** — the previous version is kept | | **History** | Lists every version with its state; **Rollback** restores an older version | | **Delete** | Removes the secret (confirmation required) | ## API and SDK lifecycle Every API, SDK, and CLI request must use the same `workspace_id` that owns the store and secret. A secret ID is not globally accessible: using an ID with another workspace correctly returns `403 FORBIDDEN` with a message that the secret does not belong to that workspace. The public lifecycle includes: | Resource | Supported operations | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Stores** | Create, list, get, update, archive, unarchive, and permanently delete | | **Secrets** | Create individually or in a batch, list metadata, get metadata, read the current value, replace or patch the value, and soft-delete | | **Versions** | List version metadata, read one version, roll back, undelete versions, and irreversibly destroy selected versions | | **Application identities** | Create AppRole or Kubernetes identities; list, get, update, disable, enable, revoke sessions, and delete | | **Access scopes** | List, add, update, and delete store-specific permissions for an identity | | **Cleanup** | Permanently delete a secret, then permanently delete its store | > **Info** > > List and metadata operations never include secret values. Use the dedicated **Get secret value** or **Get secret version** operation when your token has `secret-store.read` scope. > **Warning** > > Destroying versions, permanently deleting a secret, and permanently deleting a store cannot be undone. The CLI requires explicit confirmation for these commands. > **Warning** > > **Get application identity access details** (`GET /secret-store/identities/{identity_id}/access`) generates a fresh AppRole `secret_id` on every call, so it needs the `secret-store.write` scope. Treat the `secret_id` like a password and do not log it. Kubernetes identities return their role, namespace, and service-account binding instead. The application runtime login and scoped secret-read endpoints use the short-lived Secret Store session token issued to an AppRole or Kubernetes workload. That session token is separate from the platform API token used by the control-plane operations above. ## Grant application access On the store's **Access** tab, click **Create Access**: | Field | Options | | ------------------------------------------ | ------------------------------------------------------------------------------ | | **Access method** | **AppRole** (VMs, servers, scripts) or **Kubernetes** (pods, service accounts) | | **Access name** | e.g. `payments-api` | | **Permission** | **Read only** or **Read & write** | | **Kubernetes namespace / Service account** | Required for the Kubernetes method | After creation, use the row actions: * **Login Details** — shows the credentials your app authenticates with (Role ID and Secret ID for AppRole; namespace and service account for Kubernetes). Opening it for an AppRole identity generates a new Secret ID each time. From here you can **Rotate secret ID** (AppRole) or **Revoke sessions** to end the identity's active sessions. * **Permissions** — lists the stores the identity can use under **Current permissions**. Under **Add permission**, pick a **Store** and a **Permission** (**Read only** or **Read & write**), and choose **Can read older versions**, **Can roll back**, or **Can permanently destroy versions** (the last two need **Read & write**). Click **Remove** on a row and confirm **Remove permission** to take a store away. * **Disable / Enable** — temporarily block an identity without deleting it. * **Delete** — removes the identity with its permissions and login details. ## Archive, restore, and delete a store From the store detail **Actions** menu: * **Archive** blocks all access to the store until you **Restore** it. Archived stores stay in the list with the **Archived** status, and their secrets are hidden until you restore them. Restoring can fail if your plan's store limit is already reached. * **Delete** (confirm with **Delete permanently**) removes the store, its secrets, and its access entries. This cannot be undone. > **Warning** > > Deleting a store deletes every secret and access identity inside it. Archive instead if you might need the store again. ## Related pages * [API tokens](/docs/tools/api-tokens) * [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles) * [Secret Store API reference](/docs/api-reference/secret-store/list-secret-stores) --- title: Email Service url: https://ibee.ai/docs/tools/email-service description: Send transactional email from your own domain over an HTTPS API. Add your domain's email authentication records, register sender addresses, send with an API key, and track delivery with emails, logs, metrics, suppressions, and signed webhooks. last_updated: 2026-10-19 --- # Email Service > Send transactional email from your own domain over an HTTPS API. Add your domain's email authentication records, register sender addresses, send with an API key, and track delivery with emails, logs, metrics, suppressions, and signed webhooks. > **Note** > > Email Service is enabled per organization. If **Email Service** is not in your sidebar, contact [support](/docs/support/contact-support) to request access. Email Service sends transactional email, such as order confirmations, password resets, and notifications, from a domain you own, like `acme.com`. Your application sends each message with one HTTPS request, and the portal shows its delivery status. * **Your domain, your DNS.** You add your domain and publish the email authentication records the portal shows (DKIM, MAIL FROM, SPF, and DMARC) at your DNS provider. Your website and existing mailbox records stay unchanged. * **HTTPS API only.** Messages are sent with `POST /v1/emails`. SMTP relay is not available. * **Send-only.** Sender addresses are identities for outgoing mail, not mailboxes. Email Service does not receive email. Domains, senders, API keys, suppressions, and webhooks are managed in the portal. They have no public API yet. ## Before you begin * An organization and a workspace. Email Service resources belong to a workspace. * Access to the DNS settings of your domain, such as `acme.com`, at your DNS provider. * To create API keys: an organization admin whose account is verified ([Verify your identity](/docs/getting-started/account-setup/verify-your-identity)). ## How it works ### Add a domain Enter your domain. IBEE prepares the email authentication records for it. ### Add the DNS records Publish the records at your DNS provider. ### Verify IBEE checks the records and verifies the domain. ### Register senders Add the exact From addresses your application will use, such as `orders@acme.com`. ### Create an API key and send Create an API key for the domain, then call `POST /v1/emails` from your application server. Delivery results appear in **Emails** and can be sent to your webhook. To open Email Service, select your organization and workspace, then click **Email Service** under **Tools** in the sidebar. The page has eight sections: **Overview**, **Emails**, **Metrics**, **Domains**, **Logs**, **API keys**, **Webhooks**, and **Settings**. **Overview** shows today's numbers in UTC (**Emails today**, **Deliverability**, **Bounce rate**, and **Complaint rate**), a 7-day chart, **Recent emails**, and a **Get started** checklist: **Add a domain**, **Verify DNS**, **Register a sender**, **Create an API key**, **Send your first email** (with cURL, Node.js, and Python samples), and the optional **Add a webhook**. ## Add a domain ### Open the Add domain dialog In **Email Service**, click **Add domain** in the **Overview** checklist or in **Domains**. ### Enter your domain Under **Sending root domain**, enter a domain you control, such as `acme.com`, with no email address or URL path. The dialog shows an example From address, such as `orders@acme.com`. You choose the real sender names later, when you register senders. ### Continue to DNS authentication Click **Continue to DNS authentication**. The domain opens on its own page with four setup steps: **Choose domain**, **Add DNS records**, **Verify connection**, and **Register sender**. If the domain already exists in the workspace, the dialog offers **Continue its setup**. **Domains** lists every sending domain with its **Status**, **Next action**, and **Created** date. Search by name, or filter by **All domains**, **Verified domains**, or **Needs setup or attention**. Click **Continue setup** or **Manage** to open a domain. A domain's page has these tabs: **Overview** (setup progress), **DNS records**, **Senders**, **Activity** (the domain's sent, delivered, bounce, and complaint figures for the last 7 days), and **Settings** (provider, verification date, root domain, and **Remove domain**). ## Add DNS records and verify > **Warning** > > Do not replace your domain's nameservers or its existing website and mailbox records. Add only the records shown. ### Wait for the records When the domain is created, IBEE prepares its records. The **Add DNS records** step says so while it waits, and the records appear automatically when ready. You don't need to add anything yet. ### Add the records at your DNS provider Open the DNS settings for your domain and add each record exactly as shown. The table lists **Purpose** (DKIM, SPF, Return-Path, or DMARC), **Type**, **Name**, **Value**, and **Priority**, with a copy button next to each name and value. **Copy setup instructions** copies all records in one step, and **Download DNS records** saves them to a file. * Copy **Name** and **Value** exactly. Names are relative to your domain, and `@` means the domain itself. * Some DNS providers add your domain to the name automatically. If yours does, don't enter it twice. * Leave TTL at your provider's default unless instructed otherwise. * On Cloudflare, set each CNAME record to **DNS only** (grey cloud). Proxied records cannot be verified. Click **I've added the DNS records** when you're done. ### Verify the connection In the **Verify connection** step, click **Verify connection**. IBEE checks the domain identity and email authentication. The page updates automatically while checks run. DNS changes can take time to appear. If a check has not passed yet, you can leave the page and return to the domain later. If the step shows **Retry setup**, click it after fixing the issue described on the page. Domains added earlier by delegating a subdomain to IBEE show **NS** records instead. Add them the same way and keep the parent domain's nameservers unchanged. ### Domain status | Status | What it means | What to do | | ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | **Setting up** | IBEE is preparing the domain. | Wait. | | **Needs DNS setup** | The DNS records are ready to add. | Add the records at your DNS provider, then click **Verify connection**. | | **Verification pending** | IBEE is waiting for the DNS records to verify. | Wait. The page updates automatically. | | **Checking nameservers** | IBEE is checking the delegation (delegated subdomains only). | Wait. | | **Configuring email** | IBEE is setting up email authentication. | Wait. | | **Retrying** | A temporary problem occurred and IBEE is retrying. | Wait. If it persists, contact support. | | **Action required** | Setup stopped and needs your input. | Read the message on the domain page, fix the issue (usually the DNS records), then click **Retry setup**. | | **Sandbox ready** | Verified for sandbox sending. | Register senders. Sandbox restrictions apply (see [Settings and limits](#settings-and-limits)). | | **Active** | DNS and email authentication are verified. | Register senders and create an API key. | | **Setup expired** | Setup was not completed in time. | Remove the domain and add it again, or contact support. | | **Suspended** | Sending from this domain is stopped. | Contact support. | | **Cancelled** | Setup was cancelled. | Add the domain again if you still need it. | | **Removing** | The domain is being removed. | Wait. | ### Remove a domain Click the remove icon on the domain's row in **Domains**, or open the domain's **Settings** tab and click **Remove domain**. Type the domain name to confirm, then click **Remove domain**. A domain that is still being set up is cancelled. For a verified domain, new sends stop before its resources are released, and the domain shows **Removing**. Afterwards, delete its records at your DNS provider. ## Register senders A sender is the exact From address your application is allowed to use. Registering a sender does not create an inbox. The API rejects any From address that is not a registered sender on an active domain. ### Open the domain When a domain is **Active** or **Sandbox ready**, open it and go to the **Register sender** step or the **Senders** tab. ### Add the sender Click **Add sender** and fill in: * **Domain**: the verified sending domain. * **Sender name**: only the part before `@`, such as `orders`, `support`, or `notifications`, up to 64 characters. The domain is added automatically. * **Display name** (optional): for example, `Acme Orders`. * **Reply-To** (optional): for example, `support@acme.com`. The sender table shows each **Address**, **Display name**, **Reply-To**, and **Status**. To set the display name and Reply-To on a message sent through the API, include `fromName` and `replyTo` in the request (see [Send an email](#send-an-email)). To remove a sender, click the remove icon on its row and confirm **Remove sender**. Applications can no longer send from that address. The row stays as **Disabled**; click **Re-enable** to use it again. ## Create an API key Applications authenticate to the send API with an Email Service **API key**. A key works only in its workspace and only for the domains you choose. It cannot manage infrastructure or change Email Service settings, and platform API tokens cannot send email. ### Open API keys In **Email Service**, open **API keys** and click **Create API key**. **Create API key** in the **Overview** checklist and **Create token** on a verified domain's page open the same dialog, with the domain preselected. ### Fill in the key * **Name**: for example, `production-app` (up to 80 characters). * **Permission**: **Sending access** (send email), **Sending + read** (send email and read an email's status), or **Read only** (read an email's status, cannot send). * **Domains**: one or more verified domains in this workspace, up to 50. **Select all** picks every verified domain. * **Expires**: **Never** (default), **30 days**, **90 days**, or **1 year**. An expired key stops working. Click **Create API key**. ### Save the key The **Save your API key** dialog shows the key once. Click **Show** or **Copy API key**, store it in your application server's secret store (never in frontend code), check **I saved the key in a safe place**, and click **Done**. The **API keys** table shows each key's **Name**, **Token** prefix, **Permission**, **Domains**, **Last used**, **Created**, **Expires**, and **Status**. Turn on **Show revoked and expired** to list inactive keys. To revoke a key, click **Revoke** on its row and confirm **Revoke key**. Every request with that key is rejected immediately. Messages that were already accepted are not cancelled. Only organization admins with a verified account can create or revoke keys. Other members can see the keys in the workspace. Email keys also appear on the organization **API Tokens** page, on the **Email Tokens** tab. There, **Create Email Token** makes a send-only token for one verified domain: choose the **Workspace**, **Sending domain**, **Token name**, and **Token expiration** (**No expiration**, **7 days**, **30 days**, **90 days** (default), or **1 year**). For platform API tokens and other credential types, see [API Tokens](/docs/tools/api-tokens). ## Send an email Send one message per request: ```http POST https://api.ibee.email/v1/emails ``` ### Headers | Header | Required | Value | | ----------------- | -------- | ------------------------------------------------------------------------------------------- | | `Authorization` | Yes | `Bearer ` | | `Content-Type` | Yes | `application/json` | | `Idempotency-Key` | Yes | A unique key for this message: 8–128 characters of letters, digits, `.`, `_`, `:`, and `-`. | ### Body | Field | Required | Description | | ---------- | ----------------------- | --------------------------------------------------------------- | | `from` | Yes | A registered sender address on a domain the key can use. | | `to` | Yes | One recipient email address, as a string. | | `subject` | Yes | 1–200 characters. | | `text` | One of `text` or `html` | Plain-text body, up to 100,000 characters. | | `html` | One of `text` or `html` | HTML body, up to 250,000 characters. | | `fromName` | No | Display name shown with the From address, up to 120 characters. | | `replyTo` | No | Reply-To email address. | Each request has exactly one recipient. To email several people, send one request per recipient, each with its own `Idempotency-Key`. Attachments, CC, and BCC are not supported. ### Examples **`cURL`** ```bash title="cURL" curl https://api.ibee.email/v1/emails \ -H "Authorization: Bearer $IBEE_API_KEY" \ -H "Idempotency-Key: order-1042-confirmation" \ -H "Content-Type: application/json" \ -d '{ "from": "orders@email.acme.com", "fromName": "Acme Orders", "to": "buyer@example.com", "replyTo": "support@acme.com", "subject": "Your order is confirmed", "text": "Thank you for your order.", "html": "

Thank you for your order.

" }' ``` **`Python`** ```python title="Python" import os import requests response = requests.post( "https://api.ibee.email/v1/emails", headers={ "Authorization": f"Bearer {os.environ['IBEE_API_KEY']}", "Idempotency-Key": "order-1042-confirmation", }, json={ "from": "orders@email.acme.com", "fromName": "Acme Orders", "to": "buyer@example.com", "subject": "Your order is confirmed", "text": "Thank you for your order.", }, timeout=30, ) response.raise_for_status() print(response.json()["id"]) ``` **`Node.js`** ```javascript title="Node.js" const response = await fetch("https://api.ibee.email/v1/emails", { method: "POST", headers: { Authorization: `Bearer ${process.env.IBEE_API_KEY}`, "Idempotency-Key": "order-1042-confirmation", "Content-Type": "application/json", }, body: JSON.stringify({ from: "orders@email.acme.com", fromName: "Acme Orders", to: "buyer@example.com", subject: "Your order is confirmed", text: "Thank you for your order.", }), }); const result = await response.json(); if (!response.ok) { throw new Error(`${result.error.code}: ${result.error.message}`); } console.log(result.id); ``` ### Response A successful request returns `202 Accepted`. This means the message was accepted and queued. Delivery happens afterwards and is reported in **Emails** and through webhooks. ```json { "id": "msg_Xk3v9Qp2LmN7tRzA", "status": "accepted", "duplicate": false } ``` ### Idempotency The `Idempotency-Key` makes retries safe. If a request fails because of a timeout or network error, retry it with the same key. When a key has already been used in the workspace, the API returns the original message's `id` with `"duplicate": true` and does not send it again. Derive the key from your own record, such as `order-1042-confirmation`. Use a new key for every distinct email. A reused key never sends a second message, even if the body changed. ### Errors Errors return a JSON body with a machine-readable `code`: ```json { "error": { "code": "recipient_suppressed", "message": "Recipient is on this workspace's suppression list." } } ``` | Status | Code | Meaning | | ------ | --------------------------------------------------------- | ------------------------------------------------------------------------- | | 400 | `idempotency_key_required` | The `Idempotency-Key` header is missing. | | 400 | `idempotency_key_invalid` | The key is not 8–128 allowed characters. | | 400 | `invalid_json` | The body is not a valid JSON object. | | 400 | `sender_invalid`, `recipient_invalid`, `reply_to_invalid` | An email address is malformed. | | 400 | `subject_invalid` | The subject is empty or longer than 200 characters. | | 400 | `body_empty` | Neither `text` nor `html` was provided. | | 401 | `api_key_required` | The `Authorization: Bearer` header is missing. | | 401 | `api_key_invalid` | The key is wrong, revoked, or expired. | | 403 | `sender_not_allowed` | The From address is not a registered sender on an active domain. | | 403 | `sender_not_allowed_by_key` | The key is not allowed to send from this sender's domain. | | 403 | `scope_missing` | The key does not have send permission. | | 403 | `tenant_inactive` | Email Service is not active for this workspace. | | 409 | `recipient_suppressed` | The recipient is on the workspace's suppression list. | | 413 | `body_too_large`, `request_too_large` | The content or the whole request is too large. | | 415 | `content_type_invalid` | `Content-Type` is not `application/json`. | | 429 | `daily_limit_reached` | The workspace's daily limit is used up. `details.limit` shows the limit. | | 429 | `quota_or_acceptance_conflict` | The message could not be accepted. Retry with the same `Idempotency-Key`. | | 500 | `internal_error` | Unexpected error. Retry with the same `Idempotency-Key`. | Every response includes an `x-request-id` header. Include it when you contact support. ### Send a test from the portal To check your setup without writing code, click **Send test email** in the **Overview** checklist or in **Emails**. Choose a registered sender under **From**, enter the **To**, **Subject**, and **Message**, then click **Send**. The result appears in **Emails**. Test emails are real messages and count toward the daily limit. ## Emails, logs, and metrics **Emails** lists every email sent from the workspace with **To**, **Status**, **Subject**, **From**, and **Sent**. Filter by **Search** (from, to, subject, or email ID), **Status**, **Domain**, and time range (the last 15 days by default), and click **Refresh** to load new results. Click an email to open its details (addresses, IDs, domain, timestamps, attempts, and tags), its delivery timeline with SMTP status codes, and its content in **Preview**, **Plain text**, **HTML source**, **Headers**, and **Attachments** tabs. | Status | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------- | | **Accepted** | The API accepted the message. | | **Queued** | Waiting to be sent. | | **Submitted** | Handed to the recipient's mail server. | | **Deferred** | Temporarily refused. Delivery is being retried. | | **Delivered** | The recipient's mail server accepted the message. | | **Bounced** | The recipient's mail server permanently rejected the message. The recipient is suppressed automatically. | | **Rejected** | The message was rejected and will not be delivered. | | **Failed** | The message could not be sent. | | **Complaint** | The recipient marked the message as spam. The recipient is suppressed automatically. | **Logs** lists the API requests your applications made with the workspace's API keys: **Endpoint**, **Status**, **API key**, **Duration**, **User agent**, and **Created**, filterable by status and key. A request's page shows its method, request ID, error code, and source. Request and response bodies are not stored. **Metrics** shows **Sent**, **Delivered**, **Bounce rate**, **Complaint rate**, **Failed**, and **In flight**, with rate charts, for the last 24 hours, 7, 30, or 90 days and for all domains or one domain. Deliverability is delivered ÷ sent, bounce rate is bounced ÷ sent, and complaint rate is complaints ÷ delivered, grouped by UTC acceptance time. ## Suppressions The suppression list holds recipients this workspace will not send to. A request to a suppressed recipient fails with `409 recipient_suppressed`. To open it, go to **Emails** and switch to **Suppressions**. Each entry shows the **Email**, its **Origin** (**Bounce**, **Complaint**, or **Manual**), and when it was **Added**. Filter by search or origin, and turn on **Show removed** to include removed entries. * **Add**: click **Add address**, enter the **Email address**, and click **Add address**. Emails to that address are rejected until you remove it. * **Remove**: open an active row's menu and click **Remove from list**. For a bounce or complaint, the dialog warns that sending again can hurt your sender reputation. If the address bounces or complains again, it is added back automatically. ## Webhooks Webhooks send signed delivery events to an HTTPS endpoint in your application. They are optional. You host the receiver. ### Add an endpoint In **Email Service**, open **Webhooks** and click **Add endpoint**. ### Enter the URL and events Enter the **Endpoint URL**, such as `https://api.example.com/webhooks/email`. It must be a public HTTPS address with no username, password, or `#fragment`. Local and private addresses are rejected. Under **Events**, keep all six events or choose the ones you need, then click **Add endpoint**. ### Copy the signing secret The **Save your signing secret** dialog shows the secret once. Copy it into your server's configuration, check **I've saved the secret**, and click **Done**. The **Webhooks** list shows each **Endpoint** with its **Events**, **Status** (**Active**, **Disabled**, or **Failing**), **Last delivery**, and **Created** date. Open an endpoint to manage it: * **Edit**: change the URL or the events. The signing secret and status stay the same. * **Send test event**: queue a test event to the endpoint. No email is sent. Available while the endpoint is enabled. * **Disable** or **Enable**: stop or resume deliveries. Events that happen while the endpoint is disabled are not sent after you enable it. * **Rotate secret**: issue a new signing secret, shown once. The old secret stops working immediately, so update your receiver right away. **Deliveries** on the endpoint page lists each event sent to the endpoint with its status, filterable by status. Open a delivery to see its attempts, next attempt, and last error. ### Events | Event | Sent when | | ------------------ | ------------------------------------------------------------------------ | | `email.delivered` | The recipient's mail server accepted the message. | | `email.deferred` | Delivery was temporarily refused and is being retried. | | `email.bounced` | The message bounced permanently. The recipient is suppressed. | | `email.rejected` | The message was rejected and will not be delivered. | | `email.failed` | The message could not be sent. | | `email.complained` | The recipient reported the message as spam. The recipient is suppressed. | Each delivery is a `POST` with a JSON body: ```json { "id": "evt_4fT8wQm1ZkP0sVnB", "type": "email.bounced", "createdAt": "2026-10-01T09:30:12.000Z", "data": { "messageId": "msg_Xk3v9Qp2LmN7tRzA", "from": "orders@email.acme.com", "to": "buyer@example.com", "subject": "Your order is confirmed", "status": "bounced", "smtpStatusCode": "550", "smtpResponse": "5.1.1 User unknown" } } ``` `data.messageId` matches the `id` returned by `POST /v1/emails`. Payloads can include more fields. Ignore any you don't use. ### Delivery and retries * Return any `2xx` status within 15 seconds to acknowledge an event. * Redirects are not followed. * Timeouts, network errors, and `408`, `425`, `429`, and `5xx` responses are retried with increasing delays. Other responses are not retried. * Retries can deliver the same event more than once. Deduplicate with the `x-ibee-event-id` header. ### Verify signatures Every delivery includes three headers: | Header | Value | | ------------------ | ----------------------------------------------- | | `x-ibee-signature` | `v1=` followed by the hex HMAC-SHA256 signature | | `x-ibee-timestamp` | The signing time, in Unix seconds | | `x-ibee-event-id` | The event ID, for deduplication | To verify a delivery: 1. Compute HMAC-SHA256 with your signing secret over the exact string `timestamp + "." + rawRequestBody`. Use the raw bytes you received, not re-serialized JSON. 2. Compare the hex digest with the value after `v1=` using a constant-time comparison. 3. Reject timestamps more than 5 minutes from your server's clock. **`Python (Flask)`** ```python title="Python (Flask)" import hashlib import hmac import os import time from flask import Flask, abort, request app = Flask(__name__) SECRET = os.environ["IBEE_WEBHOOK_SECRET"].encode() TOLERANCE_SECONDS = 300 @app.post("/webhooks/email") def ibee_email_webhook(): raw_body = request.get_data() timestamp = request.headers.get("x-ibee-timestamp", "") signature = request.headers.get("x-ibee-signature", "") if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: abort(400) expected = hmac.new(SECRET, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest() if not signature.startswith("v1=") or not hmac.compare_digest(signature[3:], expected): abort(400) event = request.get_json() # Skip events whose x-ibee-event-id you have already processed. print(event["type"], event["data"].get("messageId")) return "", 204 ``` **`Node.js (Express)`** ```javascript title="Node.js (Express)" import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.IBEE_WEBHOOK_SECRET; const TOLERANCE_SECONDS = 300; app.post("/webhooks/email", express.raw({ type: "application/json" }), (req, res) => { const timestamp = req.get("x-ibee-timestamp") ?? ""; const signature = req.get("x-ibee-signature") ?? ""; const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS; const expected = crypto .createHmac("sha256", SECRET) .update(`${timestamp}.`) .update(req.body) .digest("hex"); const received = signature.startsWith("v1=") ? signature.slice(3) : ""; const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); if (!fresh || !valid) return res.sendStatus(400); const event = JSON.parse(req.body.toString("utf8")); // Skip events whose x-ibee-event-id you have already processed. console.log(event.type, event.data.messageId); res.sendStatus(204); }); app.listen(3000); ``` Keep the signing secret on your server. Never put it in frontend code. ## Settings and limits **Settings** shows the workspace's **Plan**, **Status**, and **Daily limit**, and a **Usage** chart of accepted emails per UTC day. To change your plan or daily limit, use the **contact support** link on that page. If sending is paused, the page shows **Suspended** and API requests are rejected with `tenant_inactive`. Workspaces start with sandbox access. A domain that shows **Sandbox ready** is verified for sandbox sending, and sandbox recipient and quota restrictions apply. To ask about production access or a higher limit, contact [support](/docs/support/contact-support). When the daily limit is reached, the API returns `429 daily_limit_reached` until the next day starts (00:00 UTC). The **Emails today** tile on **Overview** shows today's count and limit. Test emails sent from the portal count toward the limit. Repeated requests with an already-used `Idempotency-Key` do not. | Limit | Value | | ----------------------------- | ----------------------------------------------------- | | Recipients per request | 1 | | Subject | 1–200 characters | | `text` body | 100,000 characters | | `html` body | 250,000 characters | | Request body | 256 KB | | `Idempotency-Key` | 8–128 characters: letters, digits, `.`, `_`, `:`, `-` | | `fromName` | 120 characters (longer values are truncated) | | Domains per API key | 1–50 (an Email Token from the API Tokens page: 1) | | Sender name (part before `@`) | 64 characters | Keep your bounce and complaint rates low. The **Overview** tiles show the targets: bounce rate below 2% and complaint rate below 0.05%. Send only to addresses that asked for your email, and respect the suppression list. ## Related * [API Tokens](/docs/tools/api-tokens): platform API tokens and the other credential types managed on the same page. * [Verify your identity](/docs/getting-started/account-setup/verify-your-identity): required before creating API keys. * [Contact support](/docs/support/contact-support): request Email Service access, production access, or help with a domain. --- title: Platform Fundamentals url: https://ibee.ai/docs/platform-fundamentals description: Learn the core concepts that shape how IBEE Solutions resources are organized, secured, and billed. last_updated: 2026-08-09 --- # Platform Fundamentals > Learn the core concepts that shape how IBEE Solutions resources are organized, secured, and billed. ## Overview > Replace this placeholder with product-accurate content. Start with the user outcome, then explain where this page fits in the broader IBEE Solutions workflow. ## When to use this * Explain the main scenario. * Call out who this page is for. * Mention any prerequisites or constraints. ## Before you begin * Account or role requirements * Product prerequisites * Required tools or API access ## Steps 1. Add the user goal in one sentence. 2. Describe the action in the console, CLI, or API. 3. Show expected output or validation steps. 4. Add rollback or cleanup guidance where relevant. ## Examples ```bash # Replace with a real example ibee --help ``` ```json { "replace": "with-a-real-api-example" } ``` ## Best practices * Use consistent naming across projects, regions, and environments. * Prefer least-privilege access for tokens, keys, and policies. * Add operational notes, limits, or cost considerations. ## Troubleshooting | Problem | Likely cause | Resolution | | ------------- | ------------ | ----------------------- | | Example issue | Placeholder | Replace with a real fix | ## Related pages * Add 2 to 4 internal links. * Add the most useful next step, not just nearby pages. --- title: Organizations and tenancy model url: https://ibee.ai/docs/platform-fundamentals/organizations-and-tenancy-model description: Understand organizations, workspaces, ownership boundaries, and how tenancy works in IBEE Solutions. last_updated: 2026-10-27 --- # Organizations and tenancy model > Understand organizations, workspaces, ownership boundaries, and how tenancy works in IBEE Solutions. IBEE Solutions uses a two-level tenancy model: **organizations** contain **workspaces**, and workspaces contain resources. Billing, team management, and access controls live at the organization level, while compute, storage, and networking resources are scoped to individual workspaces. ## Tenancy hierarchy ``` Account (your login) └── Organization (billing, team, API tokens) └── Workspace (VMs, storage, networking, firewalls) ``` * **Account** — your login identity. One account can own or be a member of multiple organizations. * **Organization** — the billing and administrative boundary. Each organization has its own wallet, payment method, invoices, team members, API tokens, and activity logs. * **Workspace** — the resource boundary within an organization. VMs, block storage volumes, object storage buckets, firewalls, load balancers, DNS zones, and other infrastructure resources belong to a workspace. ## What lives where | Level | What it contains | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization** | Billing (wallet, invoices, payment method, usage limits), team members, API tokens, activity logs, organization settings, KYC/verification status | | **Workspace** | Cloud VMs, GPU VMs, bare metal servers, object storage buckets, block storage volumes, load balancers, DNS zones, VPCs, firewalls, SSL certificates, backups, snapshots, ISOs, SSH keys, secret manager, container registry | ## URL structure The portal URL reflects the tenancy model: | Scope | URL pattern | Example | | --------------------- | ----------------------------------------------------- | -------------------- | | Organization home | `/organizations/{orgId}/workspaces` | Workspace listing | | Organization settings | `/organizations/{orgId}/settings` | Organization details | | Billing | `/organizations/{orgId}/billing/summary` | Billing summary | | Team | `/organizations/{orgId}/users` | Team members | | Workspace resource | `/organizations/{orgId}/workspaces/{wsId}/{resource}` | Cloud VMs list | ## Creating an organization See [Create an organization](/docs/getting-started/account-setup/create-an-organization) for the step-by-step process. Each organization requires a name, account type (Business or Individual), billing address, and currency. You can own up to 3 organizations and join up to 20 by default — see [Organization limits](/docs/platform-fundamentals/limits-and-quotas#organization-limits). To update an organization's name, address, or tax details later, see [Organization settings](/docs/platform-fundamentals/organization-settings). ## Switching organizations Use the **organization switcher** dropdown in the top navigation bar to move between organizations. You can also return to the Organizations page and select a different card. ## Workspaces When you open an organization, you land on the **Workspaces** page. Select a workspace to access its resources. Resources like VMs, storage, networking, and SSH keys are scoped to the active workspace. Every new organization starts with three workspaces — **production**, **dev**, and **stage**. An organization can have up to 5 workspaces; Admins can create more and rename them from the Workspaces page. See [Dashboard & navigation](/docs/getting-started/overview/dashboard-navigation#workspaces-page). Organization-level concerns — billing, team, API tokens, and activity logs — are in the sidebar's **Organization** and **Billing** sections at the organization level. Inside a workspace, the sidebar shows only workspace resources; use **Workspace Details** or the organization switcher to go back. ## Billing scope Billing is aggregated at the organization level. All resources across all workspaces in an organization share the same wallet balance, payment method, and invoices. Usage limits and quotas also apply at the organization level. Before creating any billable resource, the portal asks Billing whether the organization can create it, including whether your plan's resource limits allow it. If Billing refuses, for example because the balance is too low or a plan limit is reached, the portal explains why. See [Billing admission checks](/docs/platform-fundamentals/billing-and-usage#billing-admission-checks). ## Best practices * Use **one organization per billing entity** — each organization gets its own invoices and payment method. * Use **workspaces to separate environments** — for example, the default `production`, `dev`, and `stage` workspaces within a single organization. * Assign **least-privilege roles** to team members at the organization level. * Use **API tokens** scoped to the whole organization, or to specific workspaces, for automation and CI/CD. ## Related pages * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Organization settings](/docs/platform-fundamentals/organization-settings) * [Billing and usage](/docs/platform-fundamentals/billing-and-usage) * [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles) * [Dashboard](/docs/getting-started/overview/dashboard-navigation) --- title: Organization Settings url: https://ibee.ai/docs/platform-fundamentals/organization-settings description: View and edit your IBEE Solutions organization's details — name, type, legal name, billing address, and tax information (GST, VAT, or sales tax) — from the Organization Details page. last_updated: 2026-10-19 --- # Organization Settings > View and edit your IBEE Solutions organization's details — name, type, legal name, billing address, and tax information (GST, VAT, or sales tax) — from the Organization Details page. The **Organization Details** page holds the information IBEE uses to identify your organization and to prepare billing documents: the organization name, type, legal name, billing address, and tax information. You enter these details when you [create the organization](/docs/getting-started/account-setup/create-an-organization) and can update most of them later. ## Open Organization Details At the organization level (for example, on the Workspaces page), click **Organization Details** under **Organization** in the sidebar. ## Who can view and edit | Role | Access | | --------------------------------------- | ------------------------------------------------------ | | **Admin** (including the primary owner) | View and edit | | **Technical**, **Collaborator** | View only | | **Billing** | Not available — Billing members see only billing pages | See [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles). ## What the page shows | Field | Notes | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Organization ID** | Unique ID of the organization. Cannot be changed. | | **Organization Name** | The nickname shown in your organization list and switcher | | **Organization Type** | **Business** or **Individual** | | **Currency** | Set automatically from the billing country. Cannot be edited here. | | **Legal Business Name** / **Full Name** | The name printed on invoices — the legal entity name for a Business, your full name for an Individual | | **Business Address** / **Personal Address** | The billing address used on invoices | | **Tax Information** | GST, VAT, or sales tax number used on billing documents | ## Edit organization details ### Start editing On **Organization Details**, click **Edit**. ### Update the fields Change the organization name, organization type, legal name, address, or tax information as needed. The organization ID and currency stay read-only. ### Add or update tax information Under **Tax Information**, choose the tax type — **GST**, **VAT**, or **Sales Tax** — and enter your number. For GST, the portal verifies the GSTIN against government records and flags a mismatch between the registered company name and the name on your organization. ### Save Click **Save**. Click **Cancel** to discard your changes. ## IP allowlist The **IP Allowlist** card on **Organization Details** controls which IP addresses can access the organization. When the list has entries, only requests from those addresses are allowed. The card shows **Your current IP**; include the address you sign in from so you keep your own access. ### Open the add dialog Click **+ Add IP Address**, or click **Add** next to **Your current IP** to prefill your current address. ### Enter the address In **Add IP to Allowlist**, enter the **IP Address or CIDR**: an IPv4 address such as `203.0.113.42`, or a range such as `203.0.113.0/24`. Add a **Name** such as `Office` and an optional **Description**. ### Add it Click **Add IP**. The entry appears in the table with its **Status** and the date it was **Added**. To take an address off the list, click **Remove** on its row. Only members who can edit organization details can add or remove entries. ## Related pages * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Organizations and tenancy model](/docs/platform-fundamentals/organizations-and-tenancy-model) * [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles) * [Billing and usage](/docs/platform-fundamentals/billing-and-usage) --- title: Team Members & Access Roles url: https://ibee.ai/docs/platform-fundamentals/team-members-access-roles description: Invite team members to your IBEE Solutions organization, assign access roles (Admin, Technical, Collaborator, Billing), and control workspace-level permissions. last_updated: 2026-10-27 --- # Team Members & Access Roles > Invite team members to your IBEE Solutions organization, assign access roles (Admin, Technical, Collaborator, Billing), and control workspace-level permissions. Team management in IBEE Solutions is organization-level. The organization owner (Primary) invites team members, assigns access roles, and controls which workspaces each member can reach. Each role determines what the member sees and does — from full organization control to read-only workspace access or billing-only views. ## Access roles Every team member holds one of four access roles: | Role | Scope | Capabilities | | ---------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Admin** | Organization-wide | Full access — workspaces, resources, billing, team management, activity logs, support, and API tokens | | **Technical** | All or selected workspaces | Read & write access to compute, storage, network, tools, support, and resource activity. No billing or team management | | **Collaborator** | All or selected workspaces | Read-only access to resources and activity. Cannot create, edit, or delete resources, manage billing, or manage team members | | **Billing** | Organization billing | View and manage Billing Summary, Usage, Invoices, Payment Method, and Usage Limits. No workspace or resource access | ### Workspace-scoped roles **Technical** and **Collaborator** roles support workspace scoping: * **All workspaces** — the member accesses every workspace in the organization, including newly created ones * **Selected workspaces** — the member accesses only the workspaces chosen during invitation. Toggle each workspace on or off **Admin** and **Billing** roles are always organization-wide and cannot be workspace-scoped. > **Warning** > > Access roles and workspace scope cannot be edited in place. To change either one, remove the member and send a new invitation with the required role and workspace access. ### Permission details | Capability | Admin | Technical | Collaborator | Billing | | --------------------------------------------- | ----- | --------------- | --------------- | ------- | | View workspaces & resources | Yes | Yes | Yes (read-only) | No | | Create, edit, delete resources | Yes | Yes | No | No | | Create workspaces | Yes | No | No | No | | View billing (Summary, Invoices, etc.) | Yes | No | No | Yes | | Manage billing (Payment Method, Usage Limits) | Yes | No | No | Yes | | View team members | Yes | Yes (read-only) | Yes (read-only) | No | | Invite, remove, and resend invitations | Yes | No | No | No | | View Organization Details | Yes | Yes (read-only) | Yes (read-only) | No | | Edit Organization Details | Yes | No | No | No | | View activity logs | Yes | Yes | Yes | No | | Access support | Yes | Yes | No | No | | Create API tokens | Yes | No | No | No | ## Primary owner The organization creator is the **Primary owner**, who always holds the Admin role. The Primary owner: * Cannot be removed from the organization * Has full access to all workspaces and settings * Manages team members, along with any other Admins * Appears at the top of the Team Members table with a "Primary owner" label * Is the only user who can [transfer ownership](#transfer-ownership) ### Transfer ownership The Primary owner can hand ownership to another member. The new owner must already be an **active** member — invite them and wait until they accept first. 1. On the **Team Members** page, click **Transfer ownership** in the Primary owner's row. 2. Under **New primary owner**, select an active team member. 3. Type the organization name exactly as shown to confirm. 4. Click **Transfer ownership**. The selected member becomes the Primary owner. You stay in the organization as an **Admin** with full organization and workspace access. Billing, resources, KYC, workspaces, and notification preferences stay with the organization. ## Invite a team member Only organization **Admins** can invite team members. ### Go to Team In the portal sidebar (organization level), click **Team** under **Organization**. ### Click Add Team Member Click **Add Team Member** in the top right of the Team Members page. ### Enter email Enter the team member's **Email Address**. This is the only required field — the invitee fills in their name and profile on acceptance. ### Choose an access role Select one of the four roles: * **Admin** — full organization access * **Collaborator** — read-only workspace access * **Billing** — billing-only organization access * **Technical** — read & write workspace access ### Select workspace access (Technical and Collaborator only) For **Technical** and **Collaborator** roles, a workspace access table appears. Each workspace is listed with a toggle switch. * **Select all** — grants access to every workspace (including future ones) * **Toggle individual workspaces** — choose exactly which workspaces the member can access At least one workspace must be selected. ### Send the invitation Click **Send Invitation**. The invitee receives an email with a link to accept. > **Info** > > Invited members must **sign up** (or log in if they already have an IBEE account) and **accept the invitation** before they gain access. Access is not granted until acceptance. ## Notification types Each role carries default notification subscriptions: | Notification type | Description | | ----------------- | ------------------------------------------------------------------- | | **Technical** | Infrastructure alerts, maintenance windows, resource status changes | | **Billing** | Invoice notifications, payment confirmations, billing alerts | | **Abuse** | Abuse reports and compliance notifications | | **Emergency** | Critical infrastructure alerts, security incidents | ### Defaults by role | Role | Default notifications | | ---------------- | ------------------------------------------ | | **Admin** | Technical, Billing, Abuse, Emergency (all) | | **Technical** | Technical, Abuse, Emergency | | **Collaborator** | Technical | | **Billing** | Billing | ## Manage team members The **Team Members** page lists all members and invitations in a table with these columns: * **Member** — name and email address * **Access Role** — Admin, Technical, Collaborator, or Billing (color-coded badge) * **Workspace Access** — "All organization workspaces", specific workspace names, or "No workspace access" (Billing role) * **Status** — **Active** for members; **Invite sent** (awaiting acceptance), **Invite expired**, or **Invitation declined** for invitations * **Actions** — for Admins: **Resend** for sent or expired invitations, and the trash icon to remove a member or invitation Technical and Collaborator members can open the Team Members page to see who is in the organization, but they can't invite, remove, or change anyone. ### Resend an invitation For an invitation that shows **Invite sent** or **Invite expired**, click **Resend**. The invitee receives a new invitation email. ### Remove a team member Click the **trash icon** to remove a member. A confirmation dialog appears. Removal: * Revokes access to the organization immediately * Removes login access to all workspaces in the organization * Cannot be undone — re-invite to restore access To assign a different access role or workspace scope, remove the member and send a new invitation with the updated selections. ### Remove an invitation Sent, expired, and declined invitations appear in the table. Click the **trash icon** to delete an invitation. ## Accepting an invitation When invited, a team member: 1. Receives an email with invitation details (organization name, role, inviter). 2. Sees the invitation on the **Organizations** page — with the inviter, role, workspace access, and expiry date — and **Accept** and **Decline** buttons. 3. Clicking **Accept** grants access immediately with the assigned role and workspace scope. 4. Clicking **Decline** marks the invitation as declined. The admin can remove it or re-invite. Invitations expire. If an invitation has expired, ask the admin to click **Resend** on the Team Members page. > **Info** > > You can be a member of up to 20 organizations that you don't own. See [Limits & Quotas](/docs/platform-fundamentals/limits-and-quotas#organization-limits). ## FAQ **What happens when "All workspaces" is selected for a Technical member?** The member gains access to every current workspace and any workspace created in the future. This is equivalent to organization-scope access for that role. **Can a Billing role member see resources?** No. Billing members see only billing pages (Summary, Usage, Invoices, Payment Method, Usage Limits) and have no workspace or resource access. ## Related pages * [Organizations and tenancy model](/docs/platform-fundamentals/organizations-and-tenancy-model) * [Organization settings](/docs/platform-fundamentals/organization-settings) * [Activity logs](/docs/platform-fundamentals/activity-logs) * [API Tokens](/docs/tools/api-tokens) * [Dashboard & Navigation](/docs/getting-started/overview/dashboard-navigation) --- title: Activity logs url: https://ibee.ai/docs/platform-fundamentals/activity-logs description: Review who did what across your IBEE Solutions organization — search, filter by service, workspace, status, and time range, open an event's details, and export the results as CSV. last_updated: 2026-10-19 --- # Activity logs > Review who did what across your IBEE Solutions organization — search, filter by service, workspace, status, and time range, open an event's details, and export the results as CSV. **Activity Logs** records actions taken across your organization — creating, changing, and deleting resources, team and billing changes, security events, and support activity — together with who performed them and whether they succeeded. Use it to answer "who changed this?", to trace a failed operation, or to keep a record for audits. ## Open Activity Logs At the organization level, click **Activity Logs** under **Organization** in the sidebar. The page covers the whole organization; when it has more than one workspace, use the **Workspace** filter to narrow it to one. Admin, Technical, and Collaborator members can open Activity Logs. Billing members cannot. Each member sees only the activity their role allows. See [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles). ## Read the list Each row is one event, newest first: | Column | What it shows | | ---------------------- | ------------------------------------------------------------------------------------------- | | **Time** | When the event happened. Hover for the full timestamp. | | **Action** | What was done, for example a create, update, restore, or delete | | **Product / resource** | The resource acted on, with its type and context (such as the VM a volume was attached to) | | **Actor** | The member who performed the action, or **System** for actions IBEE performed automatically | | **Source service** | The IBEE service that recorded the event | | **Status** | **Succeeded**, **Failed**, **In progress**, **Accepted**, or **Cancelled** | Click a row to expand its details: | Detail | Notes | | ---------------------- | -------------------------------------------------------------------------------------------------- | | **Time** | Full date and time | | **Product / resource** | Product, resource type, name, and ID | | **Workspace** | The workspace the resource belongs to, when it has one | | **Actor** | Name, email, and the IP address the action came from | | **Source service** | The service that recorded the event | | **Changed** | The fields that changed, for update events | | **Reason** | For failed events: the error code, the HTTP status, and — for bulk actions — how many items failed | | **Reference** | The event ID. Click to copy it — include it when you contact support about an event. | ## Search and filter Use the controls above the list. Filters combine, and the list reloads as you change them. | Control | Options | | -------------- | -------------------------------------------------------------------------------------------------- | | **Search** | Matches a user, resource, or action | | **Service** | All services, Compute, Storage, Network, Billing, Organization, Security, Registry, Support, Email | | **Workspace** | All workspaces or one workspace | | **Status** | All statuses, Succeeded, Failed, In progress, Accepted, Cancelled | | **Time range** | Last 24 hours, Last 7 days, **Last 30 days** (default), Last 90 days | The list loads in pages. Click **Load more** at the bottom to see older events, and the refresh button next to **Export CSV** to fetch new ones. > **Tip** > > To investigate a failed operation, set **Status** to **Failed**, then expand the event to read the **Reason** and copy its **Reference**. ## Export to CSV Click **Export CSV** to download the events that match your current search, filters, and time range. The file is named `activity--.csv`. The button is disabled when the list is empty. If the export is too large, the portal shows an error — narrow the time range or add a filter, then export again. ## Troubleshooting **"No activity in this period."** Nothing was recorded in the selected time range. Choose a longer range, up to **Last 90 days**. **"No activity matches these filters."** Clear the search box or set the filters back to **All** to widen the results. **I can't see Activity Logs in the sidebar.** Your role does not include activity access — Billing members cannot view it. Ask an organization Admin to change your role. ## Related pages * [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles) * [Organizations and tenancy model](/docs/platform-fundamentals/organizations-and-tenancy-model) * [Contact Support](/docs/support/contact-support) --- title: Billing and usage url: https://ibee.ai/docs/platform-fundamentals/billing-and-usage description: Learn how billing works in IBEE Solutions — prepaid wallet credits or Invoice Billing, the billing summary, usage charts, invoices, billing checks before creation, and plan limits. last_updated: 2026-10-27 --- # Billing and usage > Learn how billing works in IBEE Solutions — prepaid wallet credits or Invoice Billing, the billing summary, usage charts, invoices, billing checks before creation, and plan limits. New IBEE Solutions organizations use a **prepaid wallet**: you add credits, and usage is deducted as resources run. Organizations approved for **Invoice Billing** are billed monthly in arrears within a credit limit instead. Before creating a new resource, the platform checks your billing state — if your wallet does not cover it or billing needs attention, you'll be asked to resolve it first. ## Billing model All billing is scoped to the **organization** level. Every workspace within an organization shares the same wallet balance, payment method, and invoices. | Concept | Description | | ------------------ | -------------------------------------------------------------------------------------------- | | **Wallet balance** | Prepaid credits available for usage. Split into **Promo balance** and **Purchased credits**. | | **Billing cycle** | The current month's accumulated usage charges. | | **Invoices** | Statements for the organization, with a PDF for each. | | **Payment method** | Cards saved on the organization (organizations outside India). | | **Usage limits** | Your plan's resource limits, such as the number of CPU VMs or total block storage size. | | **Currency** | Amounts are shown in your organization's billing currency (INR or USD). | The billing pages are under **Billing** in the sidebar: **Summary**, **Usage**, **Invoices**, **Payment Method**, and **Usage Limits**. Only members with the **Admin** or **Billing** role can open them; other members see *"You don't have access to billing for this organization."* See [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles). ## Billing summary **Billing → Summary** shows the current billing cycle: * **Current cycle** — the total so far this month, with the cycle dates and when it was computed. * **Usage charges** — charges grouped by product category. Click a category or product to expand it; each line shows **Component**, **Usage**, **Rate**, and **Amount**. When charges name individual resources, switch between **By category** and **By resource**. Everything starts collapsed. Amounts do not include sales tax. Click **Refresh** to reload. ## Usage **Billing → Usage** charts usage over time. 1. Choose a period: **24 hours**, **7 days**, **30 days** (default), or **90 days**. 2. Choose **Cost** to chart spend per service, or **Units** to chart metered quantities (shown when unit data is available). The page shows the **Total for period**, a card per service with its share of the total, and a **Breakdown** table per product with **Component**, **Plan**, **Usage**, **Rate**, and **Amount**. If some hours of usage were not recorded, a notice says how many; gaps are left blank rather than estimated. ## Invoices **Billing → Invoices** lists the organization's invoices, newest first, with **Date**, **Type**, **Number**, **Amount**, **Due date**, and **Status** (for example **Paid**, **Payment due**, or **Overdue**). Click the download icon on a row to open the invoice PDF; it is disabled until the PDF is ready. ## Invoice Billing For an organization on Invoice Billing, **Billing → Payment Method** shows an **Invoice Billing** card instead of the purchase flow: * **Credit used** against the credit limit, with the percentage used. * **This month**, **Earlier months not yet invoiced**, and **Unpaid invoices** — what the credit used is made of. * **Payment terms** and the **Next invoice** date. At 80% of the limit the card warns you. When the limit is reached, new resources are blocked until unpaid invoices are paid; running resources are not affected. Click **Request higher limit** to ask support for a higher limit, or **View invoices** to open the invoice list. To apply for Invoice Billing, see [Add billing](/docs/getting-started/account-setup/add-billing#apply-for-invoice-billing). ## Billing admission checks Before creating a billable resource — for example a Cloud VM, GPU VM, block storage volume, snapshot, bucket, load balancer, reserved IP, CDN distribution, custom domain, secret, or container registry — the portal asks Billing whether the organization can create it. Creation continues only when Billing allows it. If Billing refuses, the portal explains why. On the VM, GPU VM, and Container Registry pages this is a **Billing needs attention** popup; other pages show the message as an error. | Situation | What to do | | --------------------------------------------------------------------- | -------------------------------------------------- | | First top-up not made yet (prepaid) | Add credits. The message shows the minimum amount. | | Wallet balance does not cover the resource | Add credits and try again. | | Billing is past due | Add credits or settle the outstanding usage. | | Credit limit reached (Invoice Billing) | Pay unpaid invoices. | | Organization is billing-suspended, or an overdue billing case is open | Resolve billing, then try again. | | Pricing could not be verified | Refresh the page or choose another plan. | When adding credits can resolve the block, the popup shows **Add Credits**. It opens **Payment Method** with the purchase dialog already open; after paying, return to the create page to continue. ### Plan limit reached If a create would go over your plan's resource limit, the portal shows a message such as *"Your plan allows N CPU VMs. Upgrade your plan or request a limit increase to add more."*, with your plan's number. Click **Request a limit increase** to open Support. See [Limits & Quotas](/docs/platform-fundamentals/limits-and-quotas). ### Use the API Public API integrations make the same check with `POST /billing/resource-eligibility` (scope `billing.read`) and continue only when `allowed` is exactly `true`. Add `resource_type`, `quantity`, and, for sized resources, `size_gb` so Billing also checks your plan's resource limits; `operation` defaults to `CREATE_RESOURCE`. The response lists the plan's `resource_limits`. When a limit refuses the request, `reason` is `resource_limit_reached`, and `resource_limit_key`, `resource_limit`, and `resource_usage` say which limit applied and how much is used. See [Billing admission before creation](/docs/api-reference/introduction#billing-admission-before-creation). Product APIs do not receive wallet balances or other client-supplied billing state. ## Adding credits Open **Billing → Payment Method** and click **Purchase credits**, or click **Add Credits** in a billing popup. See [Add billing](/docs/getting-started/account-setup/add-billing). ## Usage limits **Billing → Usage Limits** shows your current tier, your billing mode, and, for each limited resource, how much is **Used**, the **Limit**, and what is **Remaining**, across all workspaces. The page is read-only; to change your plan, raise a support request. See [Limits & Quotas](/docs/platform-fundamentals/limits-and-quotas). ## Restricted or suspended organizations If an organization is restricted — for example for an overdue payment — a red banner appears at the top of every page. You can still view resources and pay, but you can't create or change anything. If an organization is suspended, its virtual machines are switched off and its resource pages are hidden. Organization details, team, **Summary**, **Invoices**, **Payment Method**, and Support stay open. The banner says what is owed and warns that the resources will be deleted if the suspension is not resolved in time. Click **Go to billing** to pay (shown to members who can open billing), or **Contact support**. ## Related pages * [Organizations and tenancy model](/docs/platform-fundamentals/organizations-and-tenancy-model) * [Add billing](/docs/getting-started/account-setup/add-billing) * [Limits and quotas](/docs/platform-fundamentals/limits-and-quotas) * [Dashboard](/docs/getting-started/overview/dashboard-navigation) --- title: Limits & Quotas url: https://ibee.ai/docs/platform-fundamentals/limits-and-quotas description: Compare IBEE Solutions plans, monthly spend thresholds, and resource allowances, see your usage against them, and learn how to request a plan change. last_updated: 2026-10-19 --- # Limits & Quotas > Compare IBEE Solutions plans, monthly spend thresholds, and resource allowances, see your usage against them, and learn how to request a plan change. Open **Billing → Usage Limits** in the portal to see your organization's current tier and billing mode and, for each limited resource, how much is **Used**, its **Limit**, and what is **Remaining**, across all workspaces. A limit shows **Unlimited** when the plan sets none and **Not included in tier** when the plan allows none. Click **Refresh** to reload, or **click here** on that page to open the plan comparison below. When a create would go over a limit, the portal refuses it with a message naming your plan's limit and a **Request a limit increase** button that opens Support. ## Plan comparison Compare the plan allowances below. **0** means not included. Your portal shows your effective limits, including approved changes.
Plan Monthly spend CPU \ VMs GPU \ VMs Block \ storage Snapshots CDN Load \ balancers Reserved \ IPs
T0 Starter INR 2,000 USD 20 1 0 100 GB 200 GB 1 1 1
T1 Basic INR 5,000 USD 50 2 0 250 GB 500 GB 3 2 2
T2 Growth INR 10,000 USD 100 4 0 500 GB 1 TB 5 3 4
T3 Scale INR 20,000 USD 200 8 1 1 TB 2 TB 10 5 8
T4 Professional INR 50,000 USD 500 12 1 2 TB 4 TB 20 8 16
T5 Business INR 1,00,000 USD 1,000 20 1 4 TB 8 TB 40 12 32
T6 Advanced INR 2,00,000 USD 2,000 30 2 6 TB 12 TB 75 20 48
T7 Enterprise INR 5,00,000 USD 5,000 40 2 10 TB 20 TB 100 30 64
T8 Enterprise Plus INR 8,00,000 USD 8,000 60 3 15 TB 30 TB 150 50 96
T9 Hyperscale INR 10,00,000 USD 10,000 80 4 20 TB 40 TB 250 75 128
CDN refers to CDN distributions. Monthly spend is shown in INR and USD. Monthly spend thresholds are shown in INR and USD; use the value for your billing currency. They are not a flat subscription price or a promise of an automatic plan change. Request a plan change through support. Storage allowances are total capacity, not the number of volumes or snapshots. In this table, 1 TB corresponds to 1,024 GB in the portal. Reserved IP allowances apply to customer-reserved addresses. **Postpaid organizations have the same resource allowances as prepaid ones.** Their credit limit is a separate, monetary check. Organization, workspace, and technical service limits are also separate from these resource allowances. ## Change your plan To change your organization's plan, raise a support request: 1. Click **Support** in the portal's top bar, then **Technical Support**. 2. Select **Others** as the product. 3. Give your organization, current tier (shown on **Billing → Usage Limits**), the plan you want, and the reason, then click **Submit Request**. A request does not change your plan or resource allowances by itself; your current plan stays active until the change is approved. See [Create a request](/docs/support/create-a-request) for the support flow. ## Organization limits These limits apply to your login rather than to a single organization: | Limit | Default | Adjustable | | -------------------------------------------- | ------- | --------------------------------------------------------------- | | Organizations you own | 3 | Yes — [request more organizations](#request-more-organizations) | | Organizations you've joined as a team member | 20 | No | The **Organizations** page shows your usage, for example *"1 of 3 owned organizations used. Joined 2 of 20 organizations."* When you reach the owned-organization limit, the **Create Organization** button is hidden. ### Request more organizations ### Open the request On the **Organizations** page, click **click here** in the usage line (it appears when you've reached your limit). If you try to create an organization while at the limit, the portal opens the same **Request More Organizations** page. ### Fill in the request In **Increase organization limit**: * **Requested total** — the total number of owned organizations you need (up to 20). * **Reason** — explain how the additional organizations will be used (20–2,000 characters). ### Send the request Click **Send request**. The usage line changes to **Request submitted** while the request waits for approval. When the request is decided, the Organizations page shows the result. If it's approved, your owned-organization limit increases. If it's rejected, your limit stays the same and the portal shows when you can apply again. ## Workspace limits | Resource | Default limit | Adjustable | | --------------------------- | ------------- | ------------------------------------------------------- | | Workspaces per organization | 5 | Yes — contact [support@ibee.ai](mailto:support@ibee.ai) | Every new organization starts with three workspaces — **production**, **dev**, and **stage** — which count toward this limit. When the limit is reached, the Workspaces page shows a **contact support** link for more workspaces. ## Product limits The [plan comparison](#plan-comparison) covers CPU VMs, GPU VMs, block storage capacity, snapshot capacity, CDN distributions, load balancers, and reserved IPs. Product-specific technical constraints are documented on the relevant product pages and are separate from plan allowances. Snapshots can capture the root disk and attached data volumes. Select **Root only**, **All attached**, or **Selective** when creating a snapshot. ## API and access limits | Resource | Default limit | Adjustable | | --------------------------- | ------------- | ---------- | | API tokens per organization | 10 | No | | SSH keys | 50 | No | To own more organizations, use the [organization limit request](#request-more-organizations). For a different resource allowance, [request a plan change](#change-your-plan). ## Related pages * [Add billing](/docs/getting-started/account-setup/add-billing) * [Create an organization](/docs/getting-started/account-setup/create-an-organization) * [Create a support request](/docs/support/create-a-request) * [Block storage](/docs/infrastructure/block-storage) * [Object storage](/docs/infrastructure/object-storage) --- title: Support url: https://ibee.ai/docs/support description: Get help from IBEE Solutions — open a Technical Support request from the portal Support Center, find organization and billing settings, and track every request in one place. last_updated: 2026-10-19 --- # Support > Get help from IBEE Solutions — open a Technical Support request from the portal Support Center, find organization and billing settings, and track every request in one place. The **Support Center** is where you ask the IBEE team for help — a server that's down, a bucket you can't reach, or a question about your account. Open a request, attach context, and follow it through to resolution from the same screen. Open the Support Center by clicking **Support** in the portal's top bar, or go to `portal.ibee.ai/organizations/{orgId}/support`. Support is available to **Admin** and **Technical** members — see [Team members & access roles](/docs/platform-fundamentals/team-members-access-roles). ## What support covers Basic technical support is included with every VM, whether you manage it from the portal, the [CLI](/docs/api-reference/cli), or the API. Raise a request from the Support Center or email [support@ibee.ai](mailto:support@ibee.ai). Each request gets a ticket number and a priority, and is tracked until it is resolved. **Included in basic support** * VM provisioning issues — a VM that isn't created or doesn't start * A VM that isn't reachable over SSH, and help recovering access (SSH keys or password reset) * Platform-level performance issues (CPU, disk, network) * Unexpected VM reboots or crashes * Resizing or upgrading vCPU, RAM and disk * Network, IP and firewall issues on IBEE's side * Help with snapshots, backups and restores * Billing and account questions **Not included in basic support** * Administration inside the operating system — installing or configuring packages, users and services * Your own applications, code, databases and third-party software * Security hardening and patching inside the VM * Recovering data when no snapshot or backup exists — see [Snapshots](/docs/tools/snapshots) and [Backups](/docs/tools/backups) ## Choose a category The Support Center landing page shows three categories. Only **Technical Support** opens a request form; the other two take you to the self-service page for that area. #### Organization Support #### Billing Support #### Technical Support To raise a billing or account question with the support team, open **Technical Support** and choose the **Others** product ("General enquiries, billing, account & anything else"). See [Create a request](/docs/support/create-a-request) for the full form. ## My Requests Below the categories, the **My Requests** card opens the list of every request raised in your organization at `portal.ibee.ai/organizations/{orgId}/support/request/all`. Each row shows the request subject, ticket number, who created it, the related resource (if any), how long ago it was opened, and its priority and status. Use **Search requests...** to find a request, and the filters to narrow by **Status**, **Priority**, or time (**Today**, **Yesterday**, **This Week**, or a custom range). | Status | Meaning | | -------------------- | ------------------------------------------------ | | **Created** | Request received | | **Assigned** | An engineer has picked up the request | | **In Progress** | The support team is working on it | | **Waiting for User** | The support team replied and needs your response | | **Resolved** | The issue is resolved | | **Closed** | The request is closed | Click any row to open the request: the message thread, the **Issue Details** you submitted, and a **Reply** option. A resolved or closed request can be reopened with **Reopen ticket** so you can reply again; if it was closed too long ago, create a new request instead. ## Response expectations You set the priority when you submit a request. Higher-priority requests are reviewed first. | Priority | Use when | | ---------- | ---------------------------------------------------------- | | **Low** | Question or minor issue with no business impact | | **Medium** | Standard issue with no immediate business impact (default) | | **High** | Significant impact requiring prompt attention | | **Urgent** | Critical — service is down or severely degraded | > **Info** > > For fastest response on critical issues, set priority to **Urgent** and include error logs or screenshots in your request. ## Contact by email | Type | Email | | ----------------- | ----------------------------------------- | | Technical support | [support@ibee.ai](mailto:support@ibee.ai) | | Abuse reports | [abuse@ibee.ai](mailto:abuse@ibee.ai) | | Sales inquiries | [sales@ibee.ai](mailto:sales@ibee.ai) | ## Related pages * [Create a request](/docs/support/create-a-request) * [Contact support](/docs/support/contact-support) --- title: Contact Support url: https://ibee.ai/docs/support/contact-support description: Get help from IBEE Solutions support — technical requests, billing queries, account issues, abuse reports, and sales inquiries via the portal or email. last_updated: 2026-09-28 --- # Contact Support > Get help from IBEE Solutions support — technical requests, billing queries, account issues, abuse reports, and sales inquiries via the portal or email. IBEE Solutions support is available through the portal and by email. Choose the channel that matches your request type. ## Support Center Open the Support Center by clicking **Support** in the portal's top bar. It is available to **Admin** and **Technical** members. #### Organization Support #### Billing Support #### Technical Support ## Email contacts | Type | Email | | ----------------- | ----------------------------------------- | | Technical support | [support@ibee.ai](mailto:support@ibee.ai) | | Abuse reports | [abuse@ibee.ai](mailto:abuse@ibee.ai) | | Sales inquiries | [sales@ibee.ai](mailto:sales@ibee.ai) | ## My Requests Track and manage all your support requests in one place. View status and reply to requests directly from the portal. Go to `portal.ibee.ai/organizations/{orgId}/support/request/all` or click **My Requests** on the Support Center page. Requests can be filtered by **Status**, **Priority**, and time range. | Priority | When to use | | -------- | -------------------------------------------------- | | Low | Question or minor issue, no business impact | | Medium | Standard issue, no immediate business impact | | High | Significant impact, needs prompt attention | | Urgent | Critical issue — service down or severely degraded | \ | Status | Meaning | | ---------------- | -------------------------------------------------------------- | | Created | Request received | | Assigned | An engineer has picked up the request | | In Progress | The support team is working on it | | Waiting for User | The support team replied and needs your response | | Resolved | Issue resolved | | Closed | Request has been closed — use **Reopen ticket** to reply again | ## Related pages * [Create a request](/docs/support/create-a-request) * [Support overview](/docs/support) --- title: Create a Support Request url: https://ibee.ai/docs/support/create-a-request description: Submit a Technical Support request from the IBEE Solutions portal. Pick a product and resource, describe your issue, set priority, attach screenshots, and track the request through resolution. last_updated: 2026-09-28 --- # Create a Support Request > Submit a Technical Support request from the IBEE Solutions portal. Pick a product and resource, describe your issue, set priority, attach screenshots, and track the request through resolution. Open the Support Center by clicking **Support** in the portal's top bar (or go to `portal.ibee.ai/organizations/{orgId}/support`). Open **Technical Support**, fill in the form, and submit. Every request you open shows up under **My Requests** for tracking and replies. ## Categories | Category | What happens when you click it | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Organization Support** | Opens **Organization Details**, where you manage your organization's settings. | | **Billing Support** | Opens the billing pages — payment methods, credits, and invoices. | | **Technical Support** | Opens the request form below. Use it for every request to the support team, including billing and account questions (choose the **Others** product). | ## Create a Technical Support request The Technical Support form is dynamic — fields appear based on the **Product** and **Issue Type** you choose. ### 1. Open Technical Support In the Support Center, click **Technical Support**. The form lives at `portal.ibee.ai/organizations/{orgId}/support/technical` with the heading *"Select a product to get started with your support request."* ### 2. Select a product Click the **Product** dropdown and pick the affected service. Each option shows a one-line description. | Product | Description | | ------------------ | --------------------------------------------------- | | **Object Storage** | S3-Compatible Object Storage | | **Cloud VMs** | Scalable Virtual Machines | | **GPU VMs** | High-Performance GPU Virtual Machines | | **Baremetal** | Dedicated Baremetal Servers | | **Load Balancer** | Load Balancer as a Service | | **Firewall** | Firewall as a Service | | **Database** | Database as a Service | | **Block Storage** | High-Performance Block Storage Volumes | | **Others** | General enquiries, billing, account & anything else | ### 3. Select a resource After choosing a product, a second dropdown appears for the specific resource (e.g. **Cloud VM**). The list shows each resource with its specs, location, and status: | Display | Example | | ---------------- | ---------------------------------------------- | | Name | `web-prod-01` | | Specs · Location | `8 vCPU · 32 GB · India - Mumbai` | | Status | Running (green) / Stopped (grey) / Error (red) | A search field at the top filters the list. ### 4. Select an issue type The **Issue Type** dropdown shows a searchable list scoped to the chosen product. For Cloud VMs: * Provisioning Failed / Instance Not Created * VM Not Reachable (SSH / RDP) * Performance Low / High CPU Usage * Unexpected Reboot / Crash * Resize / Upgrade Request Additional fields appear under the dropdown based on which issue type you pick. ### 5. Fill in the issue details Each issue type renders its own structured fields. Examples: **VM Not Reachable (SSH / RDP)** | Field | Type | | -------------------------------------- | ----------------------------- | | Which IP is affected? | Public IP / Private IP / Both | | Access Method | SSH / RDP / Console / VNC | | When did it start? | Date & time | | Any firewall / security group changes? | Yes / No | | Attach error / log output | Text area | **Resize / Upgrade Request** | Field | Type | | ------------------------------- | ------------------------------------- | | Upgrade Type \* | Multi-select: vCPU, RAM, Disk Size | | Downtime allowed? \* | Yes / No | | Preferred Maintenance Window \* | ASAP / Schedule specific time / Other | ### 6. Set priority and details Every request also shares these fields: | Field | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Region / Site** (optional) | The site your issue is in. Leave it empty if you're not sure — it's filled in from the resource when you picked one. | | **Priority** \* | `Low` / `Medium` (default) / `High` / `Urgent` | | **Additional Details** \* | Free-text, at least 20 characters — *"Describe the issue or request in detail…"* | | **Attachments** (optional) | Upload screenshots or images — PNG, JPG, JPEG, GIF, WebP (Max 10 MB each) | ### 7. Submit Click **Submit Request**. The request is created and appears under **My Requests**. ## Track your requests Click **My Requests** in the Support Center, or open `portal.ibee.ai/organizations/{orgId}/support/request/all`. The **Support Requests** page lists your organization's requests with a **Search requests...** field and filters for **Status**, **Priority**, and time range. Each row shows: | Field | Example | | ---------- | ----------------------------------------------------------------------------------- | | Title | `Server Not Reachable` | | Ticket # | `#07248819` | | Created by | The member who opened the request | | Resource | `in-vga-pi-r02-srv01` | | Age | `28d ago` | | Priority | `Low` / `Medium` / `High` / `Urgent` | | Status | `Created` / `Assigned` / `In Progress` / `Waiting for User` / `Resolved` / `Closed` | Click a row to open the full request detail. ## Request detail view The detail panel shows the full message thread plus an **Issue Details** card with the structured fields you filled in at submission time. For a *"Server Not Reachable"* request: | Field | Example | | --------------------------- | ----------------------- | | Which IP is not reachable? | `Ipmi` | | Issue Type | `Ssh Fails` | | When did it start? | `Mar 6, 2026, 10:12 AM` | | Business Impact | `Partial Service` | | Is IPMI / iDRAC accessible? | `No` | | Any recent changes made? | `None` | The header shows the title, who created the request, its age, ticket number, status badge, and priority badge. ## Reply to a request Click **Reply** at the bottom-right of the detail panel to open the **Writing a Reply** composer. | Field | Description | | ----------- | -------------------------------------------------------- | | Message | Free-text — *"Type your reply…"* | | Attachments | Click to upload images — PNG, JPG, GIF, WebP — Max 10 MB | Click **Send Reply** to post. **Cancel** discards the draft. ### Reopen a resolved or closed request You can't reply to a request that is **Resolved** or **Closed**. Open it and click **Reopen ticket** to continue the conversation. If the request was closed too long ago, the portal says it can't be reopened — click **Create a new support ticket** instead. ## Tips for faster resolution * **Pick the right product and resource** — the support team uses these to scope their investigation. * **Set Priority honestly** — `Urgent` is for downtime; over-using it slows everyone down. * **Attach logs and screenshots** — paste error output into Additional Details and attach screenshots showing the symptom. * **Mention what changed recently** — recent deploys, network changes, or scaling events often correlate with the issue. ## Related pages * [Support overview](/docs/support) * [Contact support](/docs/support/contact-support) --- title: Introduction url: https://ibee.ai/docs/api-reference/introduction description: Overview of the IBEE Solutions public API. last_updated: 2026-10-27 --- # Introduction > Overview of the IBEE Solutions public API. The IBEE Solutions API gives you programmatic access to your infrastructure. You can manage virtual machines, object storage buckets, secrets, and more — all from your own code or automation tools. ## Base URL All API requests use the following base URL: ``` https://api.ibee.ai/v1 ``` ## Workspace scoping Every API request must include a `workspace_id` query parameter. This scopes the request to a specific workspace within your organization. ```bash curl https://api.ibee.ai/v1/object-storage/buckets?workspace_id=907479 \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` Workspaces isolate resources so that production, staging, and development environments stay separate. You choose which workspaces a token can access when you create it. ## Billing on create Public API integrations use the same centralized billing admission flow as the IBEE portal. The gateway asks Billing before it forwards a billable create request to the product service, so you don't need a separate call first. When Billing refuses, the create returns `402` with `"error": "billing_denied"` and Billing's reason in `billing_reason`, and nothing is provisioned. A create needs only the product's write scope. To check ahead of time, for example to show the answer in your own interface, call `POST /billing/resource-eligibility` for the same workspace: ```bash curl -X POST \ "https://api.ibee.ai/v1/billing/resource-eligibility?workspace_id=907479" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"sku_code":"OBJECTST-STD"}' ``` This check needs the `billing.read` scope. Its answer is point-in-time and reserves nothing, so the create itself can still be refused. To have Billing also check your plan's resource limits, add `resource_type` (for example `cpu_vm`, `block_volume` or `public_ipv4`), `quantity`, and `size_gb` for sized resources. `operation` defaults to `CREATE_RESOURCE`. The response lists the plan's `resource_limits`; when a limit refuses the request, `reason` is `resource_limit_reached` and `resource_limit_key`, `resource_limit` and `resource_usage` say which limit and how much is used. Billing state and prices are evaluated by the shared billing admission layer. Do not send wallet balances, credit limits, or other billing state to product APIs. ## Available resources | Resource | Description | | ---------------------- | ---------------------------------------------------------------------------- | | **Secret Store** | Create stores, manage secrets, and retrieve values. | | **Object Storage** | Create and manage S3-compatible storage buckets. | | **Compute catalog** | Discover placement sites, plans, and compatible OS images. | | **Cloud VMs** | Deploy and manage cloud virtual machines. | | **GPU VMs** | Deploy and manage GPU-accelerated virtual machines for AI/ML workloads. | | **VPC networking** | Manage isolated networks, subnets, VM attachments, NAT, and port forwarding. | | **Reserved IPs** | Reserve and move portable public IPv4 addresses. | | **Firewalls** | Manage firewall groups, rules, and VM attachments. | | **Load balancers** | Provision and manage L4 and L7 load balancers. | | **Block storage** | Create, attach, detach, resize, and delete volumes. | | **CDN** | Manage distributions, website settings, custom domains, and cache purges. | | **Container Registry** | Manage registries, registry access tokens, repositories, and images. | | **VM console** | Open and close browser console sessions for VMs. | | **Billing** | Check ahead of time whether a workspace may create a billable resource. | ## Response format All responses are JSON. Successful responses return the resource directly. ## Errors Every error uses one body. A refusal from the gateway carries a machine-readable `error` code, plus `required_scope`, `billing_reason`, `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` (each `null` when it does not apply). A refusal from the product service behind the gateway carries `detail` instead. ```json { "error": "insufficient_scope", "required_scope": "vm.write", "billing_reason": null, "billing_sku_code": null, "billing_evaluated_at": null, "admission_context_id": null } ``` | Status | Gateway `error` codes | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `workspace_id_required`, `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required` or `invalid_site_id`. | | `401` | `invalid_api_key` — the token is missing, malformed, or unknown. | | `402` | `billing_denied` — Billing refused the request. `billing_reason` carries Billing's reason, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required` or `resource_limit_reached`. Nothing is provisioned. | | `403` | `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member`, `principal_permission_denied`; on writes also `organization_restricted` and `verification_required`. | | `423` | `organization_suspended` — writes are refused while the organization is suspended. | | `429` | A concurrency limit was reached, for example too many console sessions. Retry later. | | `503` | A service the request depends on did not answer, for example `billing_admission_unavailable` or `workspace_verification_unavailable`. | `404` and `409` come from the product service with `detail`. Each endpoint in the API reference lists the statuses it can return. ## Pagination The cloud VM, GPU VM, and firewall group lists return 10 records unless you pass `limit` (at most 100). Use `offset` to read the next page: ```bash curl "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=907479&limit=100&offset=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` Other lists have their own `limit` default and maximum, shown on each endpoint. ## Async operations Some operations — creating, deleting, starting, stopping, or rebooting virtual machines — are asynchronous. These endpoints return `202 Accepted` with an `operation_id` you can poll: ```json { "operation_id": "op_123", "vm_id": "vm_abc123", "status": "accepted", "submitted_at": "2026-07-01T12:00:00Z" } ``` Use the [Get operation status](/docs/api-reference/cloud-vms/get-compute-operation) endpoint to check progress. ## VM network options and delete VM create accepts launch network options: `vpc_id` with `subnet_id`, `network_connectivity` (`private`, `nat` or `public_ip`), `vpc_attachment_mode` (`primary` or `secondary`) and `reserved_public_ip_id`. Omit them to launch on the public provider network. Inline public keys go in `ssh_keys`, next to saved keys in `ssh_key_ids`. See [Create a cloud VM](/docs/api-reference/cloud-vms/create-cloud-vm) for the rules that combine them. VM delete takes an optional body. A VM whose public IP was assigned automatically is refused with `400` unless you set `public_ip_action`: `release` releases the address with the VM, and `reserve` keeps it as a Reserved IP (send `reserved_ip_billing_catalog` with it, and optionally `reserved_ip_label`). ```bash curl -X DELETE "https://api.ibee.ai/v1/compute/cloud-vms/vm_abc123?workspace_id=907479" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "X-Idempotency-Key: delete-vm-abc123" \ -H "Content-Type: application/json" \ -d '{"public_ip_action":"release"}' ``` ## Idempotency VM create, delete, and power operations require an `X-Idempotency-Key` header. If one of these requests fails due to a network issue, you can safely retry it with the same key. Other write operations do not currently require this header; follow the requirement shown on each endpoint. ```bash curl -X POST "https://api.ibee.ai/v1/compute/cloud-vms/vm_abc123/actions/reboot?workspace_id=907479" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "X-Idempotency-Key: reboot-vm-abc123-1" ``` For a VM create, see [Create a cloud VM](/docs/api-reference/cloud-vms/create-cloud-vm): its body takes `site_id` from `GET /compute/sites`, and `plan_id` with the plan's `billing_catalog` object, unchanged, from `GET /compute/plans`. ## Machine-readable access Everything in this reference is also available as data, for code generators and AI agents: | What | Where | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OpenAPI 3.1 specification, complete (the same file at each address) | [openapi.yaml](https://ibee.ai/docs/openapi.yaml) · [openapi.json](https://ibee.ai/docs/openapi.json) · [/docs/openapi/ibee-cloud.yaml](https://ibee.ai/docs/openapi/ibee-cloud.yaml) | | API catalog ([RFC 9727](https://www.rfc-editor.org/rfc/rfc9727)) | [/.well-known/api-catalog](https://ibee.ai/.well-known/api-catalog) | | Index of every docs page, one line each | [/docs/llms.txt](https://ibee.ai/docs/llms.txt) | | Full text of every docs page in one file | [/docs/llms-full.txt](https://ibee.ai/docs/llms-full.txt) | | Markdown of any page | append `.md` to its URL, for example [create-cloud-vm.md](https://ibee.ai/docs/api-reference/cloud-vms/create-cloud-vm.md) | | MCP server for AI clients (Claude Code, Cursor and others) | `https://ibee.ai/docs/_mcp/server` | ```bash claude mcp add --transport http ibee-docs https://ibee.ai/docs/_mcp/server ``` ## Next steps * [Authentication](/docs/api-reference/authentication) — Create and use API tokens. * [SDKs](/docs/api-reference/sdk-overview) — Official Python (`pip install ibee`) and TypeScript (`npm install ibee-sdk`) client libraries. * [CLI](/docs/api-reference/cli) — Manage resources from the terminal (`pip install ibee-cli`). * [Rate limits](/docs/api-reference/rate-limits) — Understand request limits. --- title: Authentication url: https://ibee.ai/docs/api-reference/authentication description: Learn how to create API tokens and authenticate your requests. last_updated: 2026-10-27 --- # Authentication > Learn how to create API tokens and authenticate your requests. Every API request must include a valid platform API token. Tokens use Bearer authentication and are scoped to your organization. ## Create an API token 1. Log in to the [IBEE portal](https://portal.ibee.ai). 2. Go to **Organization → API Tokens**. 3. Click **Create Token**. 4. Give the token a name, select the scopes it needs, and choose a workspace policy. 5. Click **Create**. Copy the token immediately — it is shown only once. > **Warning** > > Store your token securely — it cannot be viewed again after creation. If a > token is lost or exposed, revoke it and create a new one. Never embed a token > in client-side code (browser or mobile apps) or commit it to source control. ## Using your token Include the token in the `Authorization` header as a Bearer token: ```bash curl https://api.ibee.ai/v1/object-storage/buckets?workspace_id=907479 \ -H "Authorization: Bearer ibee_prod_key_xxxxxxxxxxxx" ``` Production tokens start with `ibee_prod_key_`. Development tokens start with `ibee_dev_key_` and must be sent to `https://api.ibee.co.in/v1`. Tokens are environment-specific; a development token is not valid against production and vice versa. ## Scopes Each token is granted specific scopes that control which resources it can access. Select the minimum scopes your integration needs. | Scope | Permission | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `secret-store.read` | List stores, get secret metadata and values. | | `secret-store.write` | Create stores, create and update secrets, and manage access identities. Reading an identity's login details also needs this scope, because each call issues a new secret ID. | | `object-storage.read` | List and read buckets. | | `object-storage.write` | Create buckets. | | `object-storage.delete` | Delete buckets. | | `network.read` | List VPCs, subnets, NAT gateways, reserved IPs, and firewall resources. | | `network.write` | Create, update, attach, and delete networking resources. | | `load-balancer.read` | List load balancers and read provisioning status. | | `load-balancer.write` | Create, update, and delete load balancers. | | `vm.read` | List and get virtual machines and operations. | | `vm.write` | Create, update, delete VMs and run power actions. | | `billing.read` | Check whether a workspace is eligible to create billable resources. | | `block-storage.read` | List volumes and read volume operation history. | | `block-storage.write` | Create, attach, detach, resize, and delete volumes. | | `cdn.read` | List CDN distributions, website settings, and custom domains. | | `cdn.write` | Manage distributions, website settings, domains, URLs, and cache purges. | | `container-registry.read` | List and get registries, storage plans, registry access tokens, repositories, images, vulnerability findings, SBOMs, and metrics. | | `container-registry.write` | Create, change, empty, and delete registries; upgrade storage plans; create, rotate, and revoke registry access tokens; delete repositories and images; rescan images. | A request to an endpoint that requires a scope the token does not have returns `403 Forbidden`. The SDKs and CLI expose an explicit billing eligibility check for previews and diagnostics. A token needs `billing.read` only when your integration calls that check directly. Billable create requests need only the corresponding product write scope: the public gateway makes a fail-closed, authoritative billing decision before it forwards the request to the existing product service. ## Workspace policies When you create a token, you choose how it accesses workspaces: | Policy | Behavior | | ----------------------- | --------------------------------------------------------------------------------------------------------- | | **Entire organization** | The token can access any workspace in the organization. | | **Specific workspaces** | The token can only access the workspaces you select. Requests to other workspaces return `403 Forbidden`. | Use **Specific workspaces** when you want to limit a CI/CD pipeline or integration to a single environment (for example, only staging). ## Revoking tokens To revoke a token: 1. Go to **Organization → API Tokens** in the portal. 2. Find the token and click **Revoke**. Revoked tokens are rejected immediately on all subsequent requests. ## Error responses | Status | Meaning | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | `invalid_api_key`: the token is missing, malformed, or unknown. | | `403 Forbidden` | The token may not make this call. `insufficient_scope` names the missing scope in `required_scope`; `key_revoked`, `key_disabled`, `key_inactive` and `key_expired` describe the token; `workspace_not_allowed` means the token's workspace policy excludes the workspace. On writes, `organization_restricted` and `verification_required` are also possible. | | `423 Locked` | `organization_suspended`: writes are refused while the organization is suspended. | The `error` field of the response body carries the code. See [Errors](/docs/api-reference/introduction#errors) for the full body and the other statuses. --- title: Rate limits url: https://ibee.ai/docs/api-reference/rate-limits description: Understand API request limits and how to handle them. last_updated: 2026-10-19 --- # Rate limits > Understand API request limits and how to handle them. The IBEE Solutions API may apply rate limits to ensure fair usage and platform stability. ## Current policy The API reference does not publish request-rate numbers, and limits can vary by environment, endpoint, and account. Do not hard-code a request rate. Contact IBEE support when you need a confirmed quota for production. The API reference documents one limit: creating a VM console session (`POST /compute/console/sessions`) returns `429` when the number of active sessions per user or per workspace is reached; `detail.code` is `user_limit` or `workspace_limit`. Close sessions you no longer need, then retry. ## Handling rate limits When the gateway returns `429 Too Many Requests`, wait before retrying. Honor a `Retry-After` header when it is present; otherwise use exponential backoff with jitter. Treat the error body as descriptive rather than parsing a fixed message. **Best practices:** * Add exponential backoff with jitter to retry logic. * Cache responses when possible instead of re-fetching. * Batch operations where the API supports it rather than making individual calls. ## Higher limits If your integration needs higher rate limits, contact [IBEE support](https://ibee.ai/support). --- title: SDKs url: https://ibee.ai/docs/api-reference/sdk-overview description: Official Python and TypeScript SDKs for the IBEE Solutions API. last_updated: 2026-10-27 --- # SDKs > Official Python and TypeScript SDKs for the IBEE Solutions API. Official client libraries for the IBEE Solutions API, version 0.5.0. | SDK | Install | Requires | | ---------- | ---------------------- | ---------------------------- | | Python | `pip install ibee` | Python 3.10+ | | TypeScript | `npm install ibee-sdk` | Node 18+ or a modern browser | Both SDKs are generated from the public API contract. Each API operation is one method named after its `operationId`: `create_cloud_vm` in Python, `createCloudVm` in TypeScript. The SDKs send your request as you write it and return the server's answer unchanged. Prices, eligibility, limits and resource states are decided by the API, not by the client. ## Configure Create an API token in the portal under **Organization → API Tokens**. Pass the token and workspace to the client, or set them in the environment: | Setting | Environment variable | | ----------- | ----------------------------------------------------------------------- | | Token | `IBEE_API_TOKEN` or `IBEE_TOKEN` | | Workspace | `IBEE_WORKSPACE_ID` (a call can still pass its own `workspace_id`) | | Environment | `IBEE_ENV=dev` for the development API with an `ibee_dev_key_...` token | The default is production, `https://api.ibee.ai/v1`. ## Python ```python from ibee import Ibee client = Ibee(token="ibee_prod_key_...", workspace_id="907479") # or Ibee() to read the environment sites = client.compute_catalog.list_compute_sites().sites plans = client.compute_catalog.list_compute_plans(vm_type="cloud", site_id=sites[0].site_id).plans operation = client.cloud_vms.create_cloud_vm( name="web-1", site_id=sites[0].site_id, plan_id=plans[0].plan_id, template_id="TEMPLATE_ID", billing_term="HOURLY", ) status = client.cloud_vms.get_compute_operation(operation.operation_id) print(status.status) # accepted, running, ..., succeeded or failed ``` `AsyncIbee` has the same methods for `asyncio`. To use the development API, pass `environment=IbeeEnvironment.DEVELOPMENT` (from `ibee`) or set `IBEE_ENV=dev`. The full method list is in [`reference.md`](https://github.com/devs-ibee/ibee-python/blob/main/src/ibee/reference.md). ## TypeScript ```typescript import { Ibee } from "ibee-sdk"; const ibee = new Ibee({ token: "ibee_prod_key_...", workspaceId: "907479" }); // or new Ibee() to read the environment const { plans } = await ibee.computeCatalog.listComputePlans({ vm_type: "cloud", site_id: "SITE_ID" }); const plan = plans[0]; const operation = await ibee.cloudVms.createCloudVm({ name: "web-1", site_id: "SITE_ID", plan_id: plan.plan_id, template_id: "TEMPLATE_ID", os_type: "linux", os_distro: "ubuntu", cpu: plan.cpu, ram_mb: plan.ram_mb, billing_term: "HOURLY", }); const status = await ibee.cloudVms.getComputeOperation({ operation_id: operation.operation_id }); ``` Methods take the request fields by their API names (`vm_id`, `site_id`, `plan_id`). To use the development API, pass `environment: IbeeEnvironment.Development` or set `IBEE_ENV=dev`. Add `.withRawResponse()` to a call to read the response headers too. ## Errors Every API error carries the HTTP status and the server's fields exactly as sent. The SDKs add no wording of their own. **`Python`** ```python title="Python" from ibee.core.api_error import ApiError try: client.cloud_vms.create_cloud_vm(name="web-1", plan_id="PLAN_ID", template_id="TEMPLATE_ID") except ApiError as error: print(error.status_code) # 402 print(error.code) # "billing_denied" print(error.billing_reason) # "resource_limit_reached" print(error.message) # the server's message, or None print(error.request_id) # the x-request-id response header ``` **`TypeScript`** ```typescript title="TypeScript" import { IbeeError } from "ibee-sdk"; try { await ibee.cloudVms.createCloudVm(request); } catch (err) { if (err instanceof IbeeError) { console.error(err.statusCode, err.code, err.billingReason, err.serverMessage, err.requestId); } throw err; } ``` Each status also has its own class, such as `PaymentRequiredError`, `ForbiddenError`, `ConflictError` and `LockedError` (in `ibee.errors` for Python). Branch on `status_code` and `code`, not on message text. ## Retries and idempotency * Write operations that take an `X-Idempotency-Key` get a random key when you pass none. Pass your own `idempotency_key` to retry a write safely across processes. * Reads are retried on 429 and 503 (Python also retries reads on 502 and 504). Writes are retried only when they carry an idempotency key, and only on 429 and 503. * VM creates are never retried, and neither is any answer that carries a billing or admission code. * At most 2 retries by default, honouring `Retry-After`. Set `max_retries` (Python) or `maxRetries` (TypeScript) to change it; `0` turns retries off. Until the API resolves VM billing SKUs itself, VM create still fills in the plan's `billing_catalog` for `billing_term`, and VM delete releases an auto-assigned public IP by default. These temporary behaviours are listed in [`held.py`](https://github.com/devs-ibee/ibee-python/blob/main/src/ibee/held.py) and [`held.ts`](https://github.com/devs-ibee/ibee-typescript/blob/main/src/wrapper/held.ts). ## Upgrading from 0.4 0.5.0 removes the client-side rule layers. Requests the SDKs used to check or refuse are now sent, and the API answers them. * **Removed:** client-side validation, billing preflights and estimators (`require_resource_eligibility`, `estimate_eligibility_cost_minor`, `billingBlockMessage`, ...), waiters (`wait_for_*`, `operations.wait`) and auto-pagers (`iter_*`, `list_all_*`, `listAll*`). Poll `get_compute_operation` instead of waiting. * **Errors:** catch `ApiError` (Python, now in `ibee.core.api_error`) or `IbeeError` (TypeScript, was `ApiError`) and read `status_code`/`statusCode` and `code`. The per-reason error classes are gone. * **Arguments:** `check_state`, `preflight_billing` and similar options are removed. `workspace_id` is optional once it is set on the client. `create_bucket` needs `region`. * **TypeScript names:** methods use the `operationId` (`cloudVms.list` → `listCloudVms`, `computeCatalog.listSites` → `listComputeSites`, `operations.get` → `cloudVms.getComputeOperation`), request fields use API names, `IbeeEnvironment.PRODUCTION` → `Production`, and `timeoutMs` → `timeoutInSeconds`. The full lists are in the [Python CHANGELOG](https://github.com/devs-ibee/ibee-python/blob/main/CHANGELOG.md) and the [TypeScript CHANGELOG](https://github.com/devs-ibee/ibee-typescript/blob/main/CHANGELOG.md). #### [Python SDK on GitHub](https://github.com/devs-ibee/ibee-python) #### [ibee on PyPI](https://pypi.org/project/ibee/) #### [TypeScript SDK on GitHub](https://github.com/devs-ibee/ibee-typescript) #### [ibee-sdk on npm](https://www.npmjs.com/package/ibee-sdk) See also the [CLI](/docs/api-reference/cli), the [Terraform provider](/docs/api-reference/terraform) and the [examples](/docs/api-reference/examples). --- title: CLI url: https://ibee.ai/docs/api-reference/cli description: Manage compute, networking, storage, and secrets from your terminal. last_updated: 2026-10-27 --- # CLI > Manage compute, networking, storage, and secrets from your terminal. The IBEE CLI (`ibee`), version 0.5.0, manages your cloud resources from the terminal. It is built on the [Python SDK](/docs/api-reference/sdk-overview): each command makes one API call and prints the server's answer. ## Install ```bash pip install ibee-cli ``` Requires Python 3.10+. This installs the `ibee` command. ## Authenticate Create an API token in the portal under **Organization → API Tokens**, then set: ```bash export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx" # or IBEE_API_TOKEN export IBEE_WORKSPACE_ID="907479" ``` Both can also be passed per command with `--token` and `--workspace`. ## Quickstart Find a site, plan, and image, then create a VM and wait for it: ```bash ibee compute sites ibee compute plans --vm-type cloud --site-id SITE_ID ibee compute images --vm-type cloud --site-id SITE_ID ibee vms create web-1 --site-id SITE_ID --plan-id PLAN_ID --template-id IMAGE_ID \ --ssh-key-file ~/.ssh/id_ed25519.pub --wait ibee vms list ibee vms delete VM_ID --yes --wait ``` Asynchronous commands return an operation. Without `--wait`, wait for it later: ```bash ibee ops wait OPERATION_ID ``` ## Common commands ```bash ibee vms get VM_ID ibee vms stop VM_ID --wait ibee gpus list ibee buckets create my-bucket --region in-south-2 ibee buckets list ibee block-storage list ibee cdn list ibee secrets stores list ibee vpcs list ibee reserved-ips list ibee firewalls list ibee load-balancers list ibee billing eligibility --resource-type cpu_vm ``` `gpus` takes the same commands as `vms`. Run `ibee --help` or `ibee GROUP --help` for every command and option. Commands that delete, detach, or release ask for confirmation; add `--yes` to skip it. ## Global options | Option | Environment variable | Description | | ------------------- | ---------------------------------- | -------------------------------------------------------- | | `--token` | `IBEE_TOKEN` (or `IBEE_API_TOKEN`) | API token | | `--workspace`, `-w` | `IBEE_WORKSPACE_ID` | Workspace ID | | `--dev` | `IBEE_ENV=dev` | Use the development API with an `ibee_dev_key_...` token | | `--base-url` | `IBEE_BASE_URL` | Custom API endpoint | | `-o`, `--output` | `IBEE_OUTPUT` | `table`, `json`, `yaml`, or `id` | | `--json` | | Same as `-o json` | | `--yes`, `-y` | `IBEE_ASSUME_YES=1` | Answer yes to every confirmation | ```bash ibee -o json buckets list | jq '.buckets[].name' ``` ## Errors and exit codes Every error prints the HTTP status and the server's fields as sent: ```text Error: HTTP 402 code: billing_denied reason: resource_limit_reached message: - request_id: 6f1c2e... ``` With `-o json` the same fields, plus the raw `body`, are printed on stderr as `{"error": {...}}`. | Exit code | Meaning | | --------- | ------------------------------------------------------------------ | | 0 | Success | | 1 | Failed operation, declined confirmation, or another error | | 2 | Usage or configuration error; nothing was sent | | 3 | `--wait` reached `--timeout` while the operation was still running | | 4 | Network error (no HTTP answer) | | 10–14 | HTTP 400, 401, 402, 403, 404 | | 15–18 | HTTP 409, 422, 423, 429 | | 19 | HTTP 5xx | ## Retries Reads are retried on 429, 502, 503, and 504. Writes are retried only on 429 and 503, and only when they carry an idempotency key; an answer with a billing or admission code is never retried. Write commands that take `--idempotency-key KEY` send it unchanged; without one, a random key is sent. After a retryable failure the CLI prints the key, so you can repeat the command without doing the write twice. ## Upgrading from 0.4 * `--check-billing`, `--check-state`, `--preflight-billing`, and the other client-side check options are removed. The API answers what they checked. * API errors exit with the codes above instead of `1`. * `billing eligibility` takes options (`--sku-code`, `--resource-type`, `--quantity`, `--size-gb`) instead of a SKU argument. * `buckets create` needs `--region`. Values the CLI used to fill in or refuse are now sent as given. * `vpcs virtual-ips` and `block-storage attach-vm`/`detach-vm` are removed; use `vms volume-attach` and `vms volume-detach` for volumes. See the [CLI CHANGELOG](https://github.com/devs-ibee/ibee-cli/blob/main/CHANGELOG.md) for the full list. ## Related * [Python SDK](/docs/api-reference/sdk-overview), the library the CLI is built on * [Examples](/docs/api-reference/examples): a `cli.sh` for every product * [`ibee-cli` on PyPI](https://pypi.org/project/ibee-cli/) and [on GitHub](https://github.com/devs-ibee/ibee-cli) --- title: Terraform url: https://ibee.ai/docs/api-reference/terraform description: Install the IBEE Terraform provider, authenticate to a workspace, and manage infrastructure as code. last_updated: 2026-10-27 --- # Terraform > Install the IBEE Terraform provider, authenticate to a workspace, and manage infrastructure as code. Use Terraform to describe IBEE infrastructure in configuration files and review changes before applying them. The `devs-ibee/ibee` provider, version 0.5.0, is published on the [Terraform Registry](https://registry.terraform.io/providers/devs-ibee/ibee/latest) and covers compute, networking, storage, secrets, and CDN. ## Before you begin * Install [Terraform](https://developer.hashicorp.com/terraform/install) 1.11 or later (1.14 or later for Terraform actions). * In the portal, open **Organization → API Tokens** and create a token for the workspace you want Terraform to manage, with the permissions your resources need. Add **Billing: Read** only if you use the `ibee_billing_eligibility` data source. See [API Tokens](/docs/tools/api-tokens). ## Get started ### 1. Set your credentials ```bash export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx" export IBEE_WORKSPACE_ID="907479" ``` Production is the default. Set `IBEE_ENV=dev` with a development token to use the development API. Keep the token out of Terraform files and source control. ### 2. Write a configuration Save this as `main.tf` in a new directory: ```hcl terraform { required_version = ">= 1.11.0" required_providers { ibee = { source = "devs-ibee/ibee" version = "~> 0.5.0" } } } provider "ibee" {} variable "site_id" { description = "An available network site ID" type = string } resource "ibee_vpc" "example" { name = "terraform-example" site_id = var.site_id } output "vpc_id" { value = ibee_vpc.example.id } ``` Find site IDs in the portal or with the [`ibee_network_sites`](https://registry.terraform.io/providers/devs-ibee/ibee/latest/docs/data-sources/network_sites) data source. ### 3. Initialize, plan, and apply ```bash terraform init terraform plan -var="site_id=SITE_ID" terraform apply -var="site_id=SITE_ID" ``` Some resources incur charges. Review every plan before you apply it. ### 4. Clean up ```bash terraform destroy -var="site_id=SITE_ID" ``` ## Errors and retries The provider calls the API and relays its answer. A failed request shows the HTTP status, the server's code and message, and the request ID. Reads are retried on 429, 502, 503, and 504; writes only on 429 and 503, and never when the answer carries a billing or admission code. ## Upgrading from 0.4 * `ibee_cloud_vm`, `ibee_gpu_vm`: `billing_interval` no longer defaults to `HOURLY`. Set it for new VMs. Changing `plan_id` now resizes the VM in place instead of replacing it, and changing `ssh_key_ids` updates access in place. * `ibee_compute_plans`: `currency` and `billing_interval` no longer default to `INR` and `HOURLY`. * `ibee_secret_store`: `force_archive` is removed. Remove it from your configuration. * `ibee_block_volume`: shrinking `size_gb` no longer replaces the volume; the API's answer is shown. * Provider-side checks (plan selectable and priced, VM power states, billing catalog rules) are removed. The API decides. See the [provider CHANGELOG](https://github.com/devs-ibee/terraform-provider-ibee/blob/main/CHANGELOG.md) for details. ## Next steps * [Provider documentation](https://registry.terraform.io/providers/devs-ibee/ibee/latest/docs) on the Terraform Registry * [Terraform examples](https://github.com/devs-ibee/examples/tree/main/terraform): a web app, a private network, a static site, and storage with secrets * [Provider source](https://github.com/devs-ibee/terraform-provider-ibee) on GitHub --- title: Examples url: https://ibee.ai/docs/api-reference/examples description: Short, runnable examples for IBEE products with the Python SDK, TypeScript SDK, CLI, and Terraform provider. last_updated: 2026-10-27 --- # Examples > Short, runnable examples for IBEE products with the Python SDK, TypeScript SDK, CLI, and Terraform provider. The [IBEE examples repository](https://github.com/devs-ibee/examples) has short, runnable examples for the 0.5.0 clients. Each one does one task, usually create a resource, read it, and delete it, with a `main.py`, an `index.ts`, and a `cli.sh`. ```bash git clone https://github.com/devs-ibee/examples.git cd examples pip install ibee ibee-cli boto3 npm install export IBEE_TOKEN="ibee_prod_key_..." export IBEE_WORKSPACE_ID="" python3 getting-started/main.py # lists the site, plan, and image IDs the other examples use npx tsx cloud-vms/index.ts bash cloud-vms/cli.sh ``` ## Compute #### [Getting started](https://github.com/devs-ibee/examples/tree/main/getting-started) Check your token and list sites, plans, and images. Nothing is created. #### [Cloud VMs](https://github.com/devs-ibee/examples/tree/main/cloud-vms) Create a VM, wait for it, read it, and delete it. #### [GPU VMs](https://github.com/devs-ibee/examples/tree/main/gpu-vms) Create, read, and delete a GPU VM. #### [VM operations](https://github.com/devs-ibee/examples/tree/main/vm-operations) Metrics, events, and moving a VM to another plan. #### [Snapshots and backups](https://github.com/devs-ibee/examples/tree/main/snapshots-and-backups) Snapshot a VM's root disk, list snapshots and backup runs. ## Storage #### [Object Storage](https://github.com/devs-ibee/examples/tree/main/object-storage) A private bucket, a bucket-scoped S3 key, and boto3. #### [Block Storage](https://github.com/devs-ibee/examples/tree/main/block-storage) Create, attach, detach, and delete a volume. #### [Container Registry](https://github.com/devs-ibee/examples/tree/main/container-registry) Build, push, and pull an image with Docker. ## Networking and security #### [VPC](https://github.com/devs-ibee/examples/tree/main/vpc) A private network with a subnet and an attached VM. #### [Reserved IPs](https://github.com/devs-ibee/examples/tree/main/reserved-ips) Reserve, attach, detach, and release a public IP. #### [Firewalls](https://github.com/devs-ibee/examples/tree/main/firewalls) A firewall group for HTTP and HTTPS attached to a VM. #### [Load Balancers](https://github.com/devs-ibee/examples/tree/main/load-balancers) An L7 HTTP load balancer in front of two VMs. #### [CDN](https://github.com/devs-ibee/examples/tree/main/cdn) Serve a public bucket with single-page-app routing and a cache purge. #### [Secret Manager](https://github.com/devs-ibee/examples/tree/main/secret-manager) A store and a versioned secret. ## Terraform #### [Terraform provider](/docs/api-reference/terraform) Install the provider from the Registry and create a VPC. #### [Terraform examples](https://github.com/devs-ibee/examples/tree/main/terraform) A load-balanced web app, a private network, a static site on the CDN, and storage with secrets. ## Interfaces | Interface | Install | Reference | | -------------- | -------------------------------------------- | ------------------------------------------------- | | Python SDK | `pip install ibee` | [SDKs](/docs/api-reference/sdk-overview) | | TypeScript SDK | `npm install ibee-sdk` | [SDKs](/docs/api-reference/sdk-overview) | | CLI | `pip install ibee-cli` | [CLI](/docs/api-reference/cli) | | HTTP | `curl` and `jq` | [API Reference](/docs/api-reference/introduction) | | Terraform | `devs-ibee/ibee` from the Terraform Registry | [Terraform](/docs/api-reference/terraform) | Most examples create billable resources for a few minutes and delete them at the end. Virtual IPs, Bare Metal Servers, SSH Keys, ISOs, and Email Service are managed in the portal and have no public API yet. --- title: List secret stores url: https://ibee.ai/docs/api-reference/secret-store/list-secret-stores last_updated: 2026-10-25 --- # List secret stores GET https://api.ibee.ai/v1/secret-store/stores Lists secret stores in a workspace. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/secret-store/stores?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/list-secret-stores ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. - `page` (integer, optional, default: 1) — Page number. - `limit` (integer, optional, default: 50) — Maximum number of records to return. - `include_archived` (boolean, optional, default: false) — Include archived stores in the result. ## Response ### 200 Stores returned successfully. - `stores` (list of SecretStore, optional) — Stores on this page. - `total` (integer, optional) — Total number of items matching the request. - `page` (integer, optional) — Page number returned (1-based). - `limit` (integer, optional) — Page size that was applied. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### SecretStore A secret store: a named container for secrets inside a workspace. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "stores": [ { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ], "total": 1, "page": 1, "limit": 50 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create secret store url: https://ibee.ai/docs/api-reference/secret-store/create-secret-store last_updated: 2026-10-25 --- # Create secret store POST https://api.ibee.ai/v1/secret-store/stores Content-Type: application/json Creates a secret store in a workspace. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl -X POST "https://api.ibee.ai/v1/secret-store/stores?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "production-secrets"}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/create-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateSecretStoreRequest. - `name` (string, required) — Display name of the store (1-128 characters). Its URL-safe form becomes `store_key`. - `description` (string, optional) — Optional description. ## Response ### 201 Store created successfully. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 402 Payment Required Error Billing refused the request (`billing_denied`). `billing_reason` carries Billing's reason unchanged, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` (a plan limit) or `resource_usage_unavailable` (Billing could not count usage). `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` identify the decision. Nothing is provisioned; resolve the reason and retry with the same idempotency key where supported. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "production-secrets" } ``` **Response** ```json { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores" querystring = {"workspace_id":"710995"} payload = { "name": "production-secrets" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"production-secrets"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"production-secrets\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"production-secrets\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"production-secrets\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995', [ 'body' => '{ "name": "production-secrets" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"production-secrets\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": "production-secrets"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get secret store url: https://ibee.ai/docs/api-reference/secret-store/get-secret-store last_updated: 2026-10-25 --- # Get secret store GET https://api.ibee.ai/v1/secret-store/stores/{store_id} Gets one secret store. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Store returned successfully. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update secret store url: https://ibee.ai/docs/api-reference/secret-store/update-secret-store last_updated: 2026-10-25 --- # Update secret store PATCH https://api.ibee.ai/v1/secret-store/stores/{store_id} Content-Type: application/json Updates store name or description. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X PATCH "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "production-secrets", "description": "Updated description"}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/update-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateSecretStoreRequest. - `name` (string, optional) — New display name. - `description` (string, optional) — New description. ## Response ### 200 Store updated successfully. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "production-secrets", "description": "Updated description" } ``` **Response** ```json { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283" querystring = {"workspace_id":"710995"} payload = { "name": "production-secrets", "description": "Updated description" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"production-secrets","description":"Updated description"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"production-secrets\",\n \"description\": \"Updated description\"\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"production-secrets\",\n \"description\": \"Updated description\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"production-secrets\",\n \"description\": \"Updated description\"\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995', [ 'body' => '{ "name": "production-secrets", "description": "Updated description" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"production-secrets\",\n \"description\": \"Updated description\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "production-secrets", "description": "Updated description" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Archive secret store url: https://ibee.ai/docs/api-reference/secret-store/archive-secret-store last_updated: 2026-10-25 --- # Archive secret store POST https://api.ibee.ai/v1/secret-store/stores/{store_id}/archive Archives a secret store. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X POST "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/archive?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/archive-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Store archived successfully. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/archive?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Unarchive secret store url: https://ibee.ai/docs/api-reference/secret-store/unarchive-secret-store last_updated: 2026-10-25 --- # Unarchive secret store POST https://api.ibee.ai/v1/secret-store/stores/{store_id}/unarchive Reactivates an archived secret store. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X POST "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/unarchive?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/unarchive-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Store reactivated successfully. - `id` (string, optional) — Unique ID of the store. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `name` (string, optional) — Display name of the store. - `store_key` (string, optional) — URL-safe slug derived from the store name. - `description` (string, optional) — Description of the store. - `status` (enum, optional) — - `active`: in use. - `archived`: archived; can be unarchived. - `deleting`: permanent deletion in progress. - Allowed values: `active`, `archived`, `deleting` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "store_123", "organization_id": "250612", "workspace_id": "907479", "name": "production-secrets", "store_key": "production-secrets", "description": "Secrets for production workloads", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/unarchive?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Permanently delete secret store url: https://ibee.ai/docs/api-reference/secret-store/permanently-delete-secret-store last_updated: 2026-10-25 --- # Permanently delete secret store DELETE https://api.ibee.ai/v1/secret-store/stores/{store_id}/permanent Irreversibly deletes a store and all store-scoped secrets, versions, identities, and policies. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X DELETE "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/permanent?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/permanently-delete-secret-store ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Store and its resources permanently deleted. - `status` (enum, required) — - `destroyed`: the versions' data was irreversibly destroyed. - `permanently_deleted`: the secret and all its versions were removed. - Allowed values: `destroyed`, `permanently_deleted` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "status": "destroyed" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/permanent?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List secrets url: https://ibee.ai/docs/api-reference/secret-store/list-secrets last_updated: 2026-10-25 --- # List secrets GET https://api.ibee.ai/v1/secret-store/stores/{store_id}/secrets Lists secret metadata in a store. Secret values are not returned. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/secrets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/list-secrets ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. - `q` (string, optional) — Optional search query. - `page` (integer, optional, default: 1) — Page number. - `limit` (integer, optional, default: 50) — Maximum number of records to return. ## Response ### 200 Secrets returned successfully. - `secrets` (list of Secret, optional) — Secrets on this page. - `total` (integer, optional) — Total number of items matching the request. - `page` (integer, optional) — Page number returned (1-based). - `limit` (integer, optional) — Page size that was applied. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### Secret A secret's metadata. Values are returned by the value endpoints only. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "secrets": [ { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ], "total": 1, "page": 1, "limit": 50 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create secret url: https://ibee.ai/docs/api-reference/secret-store/create-secret last_updated: 2026-10-25 --- # Create secret POST https://api.ibee.ai/v1/secret-store/stores/{store_id}/secrets Content-Type: application/json Creates a secret in a store. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X POST "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/secrets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"secret_name": "database-url", "value": {"url": "postgres://user:pass@host:5432/mydb"}}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/create-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateSecretRequest. - `secret_name` (string, required) — Unique name for the secret within the store. Lowercase alphanumeric and hyphens only. - `value` (map from string to any, required) — Key-value pairs containing the secret data. ## Response ### 201 Secret created successfully. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 402 Payment Required Error Billing refused the request (`billing_denied`). `billing_reason` carries Billing's reason unchanged, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` (a plan limit) or `resource_usage_unavailable` (Billing could not count usage). `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` identify the decision. Nothing is provisioned; resolve the reason and retry with the same idempotency key where supported. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "secret_name": "database-url", "value": { "url": "postgres://user:pass@host:5432/mydb" } } ``` **Response** ```json { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets" querystring = {"workspace_id":"710995"} payload = { "secret_name": "database-url", "value": { "url": "postgres://user:pass@host:5432/mydb" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"secret_name":"database-url","value":{"url":"postgres://user:pass@host:5432/mydb"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995" payload := strings.NewReader("{\n \"secret_name\": \"database-url\",\n \"value\": {\n \"url\": \"postgres://user:pass@host:5432/mydb\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"secret_name\": \"database-url\",\n \"value\": {\n \"url\": \"postgres://user:pass@host:5432/mydb\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"secret_name\": \"database-url\",\n \"value\": {\n \"url\": \"postgres://user:pass@host:5432/mydb\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995', [ 'body' => '{ "secret_name": "database-url", "value": { "url": "postgres://user:pass@host:5432/mydb" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"secret_name\": \"database-url\",\n \"value\": {\n \"url\": \"postgres://user:pass@host:5432/mydb\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "secret_name": "database-url", "value": ["url": "postgres://user:pass@host:5432/mydb"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Batch-create secrets url: https://ibee.ai/docs/api-reference/secret-store/batch-create-secrets last_updated: 2026-10-25 --- # Batch-create secrets POST https://api.ibee.ai/v1/secret-store/stores/{store_id}/secrets:batchIngest Content-Type: application/json Creates up to 500 secrets without overwriting existing names. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X POST "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/secrets:batchIngest?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"secrets": [{"secret_name": "", "value": {}}]}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/batch-create-secrets ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a BatchCreateSecretsRequest. - `secrets` (list of BatchCreateSecretItem, required) — Secrets to create (1-500). ## Response ### 200 Batch processed; inspect each result for created, skipped, or failed status. - `results` (list of BatchCreateSecretResult, required) — One result per requested secret, in request order. - `created_count` (integer, required) — Number of secrets created. - `skipped_count` (integer, required) — Number of secrets skipped because they already existed. - `failed_count` (integer, required) — Number of secrets that failed to create. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### BatchCreateSecretItem One secret in a batch create. - `secret_name` (string, required) — Unique name for the secret within the store (2-64 characters). - `value` (map from string to any, required) — Key-value pairs containing the secret data. ### BatchCreateSecretResult Outcome for one secret in a batch create. - `secret_name` (string, required) — Name of the secret the result refers to. - `status` (enum, required) — - `created`: the secret was created. - `skipped`: a secret with this name already existed. - `failed`: creation failed; see `error`. - Allowed values: `created`, `skipped`, `failed` - `secret` (Secret, optional, nullable) — The created secret, when `status` is `created`. - `error` (string, optional, nullable) — Error detail when `status` is `failed`. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ### Secret A secret's metadata. Values are returned by the value endpoints only. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Examples **Request** ```json { "secrets": [ { "secret_name": "", "value": {} } ] } ``` **Response** ```json { "results": [ { "secret_name": "", "status": "created", "secret": { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" }, "error": "" } ], "created_count": 1, "skipped_count": 1, "failed_count": 1 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest" querystring = {"workspace_id":"710995"} payload = { "secrets": [ { "secret_name": "", "value": {} } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"secrets":[{"secret_name":"","value":{}}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995" payload := strings.NewReader("{\n \"secrets\": [\n {\n \"secret_name\": \"\",\n \"value\": {}\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"secrets\": [\n {\n \"secret_name\": \"\",\n \"value\": {}\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"secrets\": [\n {\n \"secret_name\": \"\",\n \"value\": {}\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995', [ 'body' => '{ "secrets": [ { "secret_name": "", "value": {} } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"secrets\": [\n {\n \"secret_name\": \"\",\n \"value\": {}\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["secrets": [ [ "secret_name": "", "value": [] ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/secrets:batchIngest?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get secret metadata url: https://ibee.ai/docs/api-reference/secret-store/get-secret last_updated: 2026-10-25 --- # Get secret metadata GET https://api.ibee.ai/v1/secret-store/secrets/{secret_id} Gets one secret metadata record. Secret value is not returned. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret returned successfully. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete secret url: https://ibee.ai/docs/api-reference/secret-store/delete-secret last_updated: 2026-10-25 --- # Delete secret DELETE https://api.ibee.ai/v1/secret-store/secrets/{secret_id} Soft-deletes a secret. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X DELETE "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/delete-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret deleted successfully. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get secret value url: https://ibee.ai/docs/api-reference/secret-store/get-secret-value last_updated: 2026-10-25 --- # Get secret value GET https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/value Gets the latest value for a secret. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/value?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret-value ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret value returned successfully. - `id` (string, optional) — Unique ID of the secret. - `secret_name` (string, optional) — Name of the secret within the store. - `data` (map from string to any, optional) — Key-value pairs containing the secret data. - `metadata` (map from string to any, optional) — Version metadata for the returned value, including `version` and `created_time`. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "secret_123", "secret_name": "database-url", "data": { "url": "postgres://user:pass@host:5432/mydb" }, "metadata": { "version": 1, "created_time": "2026-06-29T00:00:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Replace secret value url: https://ibee.ai/docs/api-reference/secret-store/update-secret-value last_updated: 2026-10-25 --- # Replace secret value PUT https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/value Content-Type: application/json Creates a new version of the secret value. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X PUT "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/value?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"value": {}}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/update-secret-value ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateSecretValueRequest. - `value` (map from string to any, required) — Key-value pairs containing the new secret data. Creates a new version. - `cas` (integer, optional, nullable) — Check-and-set: only update if the current version matches this number. Prevents overwriting concurrent changes. ## Response ### 200 Secret value updated successfully. - `id` (string, optional) — Unique ID of the secret. - `secret_name` (string, optional) — Name of the secret within the store. - `data` (map from string to any, optional) — Key-value pairs containing the secret data. - `metadata` (map from string to any, optional) — Version metadata for the returned value, including `version` and `created_time`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json {} ``` **Response** ```json { "id": "secret_123", "secret_name": "database-url", "data": { "url": "postgres://user:pass@host:5432/mydb" }, "metadata": { "version": 1, "created_time": "2026-06-29T00:00:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value" querystring = {"workspace_id":"710995"} payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PUT', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Patch secret value url: https://ibee.ai/docs/api-reference/secret-store/patch-secret-value last_updated: 2026-10-25 --- # Patch secret value PATCH https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/value Content-Type: application/json Merges the supplied keys into the current value and creates a new version. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X PATCH "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/value?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"value": {}}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/patch-secret-value ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a PatchSecretValueRequest. - `value` (map from string to any, required) — Key-value pairs to merge into the current value. Creates a new version. ## Response ### 200 Secret value patched successfully. - `id` (string, optional) — Unique ID of the secret. - `secret_name` (string, optional) — Name of the secret within the store. - `data` (map from string to any, optional) — Key-value pairs containing the secret data. - `metadata` (map from string to any, optional) — Version metadata for the returned value, including `version` and `created_time`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json {} ``` **Response** ```json { "id": "secret_123", "secret_name": "database-url", "data": { "url": "postgres://user:pass@host:5432/mydb" }, "metadata": { "version": 1, "created_time": "2026-06-29T00:00:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value" querystring = {"workspace_id":"710995"} payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995" payload := strings.NewReader("{}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/value?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Undelete secret versions url: https://ibee.ai/docs/api-reference/secret-store/undelete-secret last_updated: 2026-10-25 --- # Undelete secret versions POST https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/undelete Content-Type: application/json Restores specified soft-deleted versions and reactivates the secret. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X POST "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/undelete?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"versions": [1]}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/undelete-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a SecretVersionsRequest. - `versions` (list of integer, required) — Secret versions to restore or irreversibly destroy. ## Response ### 200 Secret versions restored successfully. - `id` (string, optional) — Unique ID of the secret. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `store_id` (string, optional) — ID of the store that holds the secret. - `store_key` (string, optional) — URL-safe key of that store. - `secret_name` (string, optional) — Name of the secret within the store. - `status` (enum, optional) — - `active`: readable. - `soft_deleted`: deleted but recoverable until permanently deleted. - Allowed values: `active`, `soft_deleted` - `created_at` (datetime, optional) — When the record was created (ISO 8601). - `updated_at` (datetime, optional) — When the record was last changed (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "versions": [ 1 ] } ``` **Response** ```json { "id": "secret_123", "organization_id": "250612", "workspace_id": "907479", "store_id": "store_123", "store_key": "production-secrets", "secret_name": "database-url", "status": "active", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete" querystring = {"workspace_id":"710995"} payload = { "versions": [1] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"versions":[1]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995" payload := strings.NewReader("{\n \"versions\": [\n 1\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"versions\": [\n 1\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"versions\": [\n 1\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995', [ 'body' => '{ "versions": [ 1 ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"versions\": [\n 1\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["versions": [1]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/undelete?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Destroy secret versions url: https://ibee.ai/docs/api-reference/secret-store/destroy-secret-versions last_updated: 2026-10-25 --- # Destroy secret versions POST https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/destroy Content-Type: application/json Irreversibly destroys specified secret versions. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X POST "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/destroy?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"versions": [1]}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/destroy-secret-versions ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a SecretVersionsRequest. - `versions` (list of integer, required) — Secret versions to restore or irreversibly destroy. ## Response ### 200 Secret versions permanently destroyed. - `status` (enum, required) — - `destroyed`: the versions' data was irreversibly destroyed. - `permanently_deleted`: the secret and all its versions were removed. - Allowed values: `destroyed`, `permanently_deleted` ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "versions": [ 1 ] } ``` **Response** ```json { "status": "destroyed" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy" querystring = {"workspace_id":"710995"} payload = { "versions": [1] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"versions":[1]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995" payload := strings.NewReader("{\n \"versions\": [\n 1\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"versions\": [\n 1\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"versions\": [\n 1\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995', [ 'body' => '{ "versions": [ 1 ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"versions\": [\n 1\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["versions": [1]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/destroy?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Permanently delete secret url: https://ibee.ai/docs/api-reference/secret-store/permanently-delete-secret last_updated: 2026-10-25 --- # Permanently delete secret DELETE https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/permanent Irreversibly deletes all versions and metadata for a secret. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X DELETE "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/permanent?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/permanently-delete-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret permanently deleted. - `status` (enum, required) — - `destroyed`: the versions' data was irreversibly destroyed. - `permanently_deleted`: the secret and all its versions were removed. - Allowed values: `destroyed`, `permanently_deleted` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "status": "destroyed" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/permanent?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List secret versions url: https://ibee.ai/docs/api-reference/secret-store/list-secret-versions last_updated: 2026-10-25 --- # List secret versions GET https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/versions Returns version metadata without secret values. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/versions?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/list-secret-versions ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret version metadata returned successfully. - `secret_id` (string, required) — Unique ID of the secret. - `secret_name` (string, required) — Name of the secret within the store. - `current_version` (integer, required) — Version number of the current value. - `oldest_version` (integer, required) — Lowest version number still retained. - `versions` (map from string to SecretVersionSummary, required) — Map of version number (as a string) to its summary. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### SecretVersionSummary Summary of one version of a secret. - `version` (integer, required) — Version number (1-based, increasing). - `created_time` (string, required) — When the version was written (RFC 3339). - `deletion_time` (string, required) — When the version was deleted (RFC 3339); empty when it is not deleted. - `destroyed` (boolean, required) — True when the version's data was irreversibly destroyed. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "secret_id": "", "secret_name": "", "current_version": 1, "oldest_version": 1, "versions": {} } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get secret version url: https://ibee.ai/docs/api-reference/secret-store/get-secret-version last_updated: 2026-10-25 --- # Get secret version GET https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/versions/{version} Returns the value and metadata for one secret version. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID # VERSION: Positive secret version number curl "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/versions/$VERSION?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret-version ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. - `version` (integer, required) — Positive secret version number. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Secret version returned successfully. - `secret_id` (string, required) — Unique ID of the secret. - `secret_name` (string, required) — Name of the secret within the store. - `version` (integer, required) — Version number. - `data` (map from string to any, required) — Key-value pairs stored in this version. - `metadata` (map from string to any, required) — Version metadata, including `version` and `created_time`. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "secret_id": "", "secret_name": "", "version": 1, "data": {}, "metadata": {} } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/versions/1?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Roll back secret value url: https://ibee.ai/docs/api-reference/secret-store/rollback-secret last_updated: 2026-10-25 --- # Roll back secret value POST https://api.ibee.ai/v1/secret-store/secrets/{secret_id}/rollback Content-Type: application/json Copies a previous version into a new current version. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SECRET_ID: Secret ID curl -X POST "https://api.ibee.ai/v1/secret-store/secrets/$SECRET_ID/rollback?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"version": 1}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/rollback-secret ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `secret_id` (string, required) — Secret ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a RollbackSecretRequest. - `version` (integer, required) — Previous version to copy into a new current version. ## Response ### 200 Previous value copied into a new current version. - `id` (string, optional) — Unique ID of the secret. - `secret_name` (string, optional) — Name of the secret within the store. - `data` (map from string to any, optional) — Key-value pairs containing the secret data. - `metadata` (map from string to any, optional) — Version metadata for the returned value, including `version` and `created_time`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "version": 1 } ``` **Response** ```json { "id": "secret_123", "secret_name": "database-url", "data": { "url": "postgres://user:pass@host:5432/mydb" }, "metadata": { "version": 1, "created_time": "2026-06-29T00:00:00Z" } } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback" querystring = {"workspace_id":"710995"} payload = { "version": 1 } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"version":1}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995" payload := strings.NewReader("{\n \"version\": 1\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"version\": 1\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"version\": 1\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995', [ 'body' => '{ "version": 1 }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"version\": 1\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["version": 1] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/secrets/019f1e4b-4a2c-71d0-a8b3-c5f92e7d1a4b/rollback?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List application identities url: https://ibee.ai/docs/api-reference/secret-store/list-secret-identities last_updated: 2026-10-25 --- # List application identities GET https://api.ibee.ai/v1/secret-store/stores/{store_id}/identities Lists AppRole and Kubernetes identities bound to a store. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/identities?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/list-secret-identities ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identities returned successfully. - `identities` (list of SecretIdentity, required) — Identities returned. - `total` (integer, required) — Total number of identities. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### SecretIdentity An application identity that authenticates to Secret Store with AppRole or Kubernetes credentials. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "identities": [ { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ], "total": 1 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create application identity url: https://ibee.ai/docs/api-reference/secret-store/create-secret-identity last_updated: 2026-10-25 --- # Create application identity POST https://api.ibee.ai/v1/secret-store/stores/{store_id}/identities Content-Type: application/json Creates an AppRole or Kubernetes identity with an initial scope for this store. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # STORE_ID: Secret store ID curl -X POST "https://api.ibee.ai/v1/secret-store/stores/$STORE_ID/identities?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"auth_method": "approle", "name": ""}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/create-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `store_id` (string, required) — Secret store ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateSecretIdentityRequest. - `auth_method` (enum, required) — Authentication method used by the application. - Allowed values: `approle`, `kubernetes` - `name` (string, required) — Display name of the identity (1-128 characters). - `token_policy_mode` (enum, optional, default: read_only) — Default access mode for the identity's tokens. - `read_only` (default) - `read_write` - Allowed values: `read_only`, `read_write` - `k8s_namespace` (string, optional, nullable) — Required when auth_method is kubernetes. - `k8s_service_account` (string, optional, nullable) — Required when auth_method is kubernetes. ## Response ### 201 Identity created successfully. Fetch access details separately. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "auth_method": "approle", "name": "" } ``` **Response** ```json { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities" querystring = {"workspace_id":"710995"} payload = { "auth_method": "approle", "name": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"auth_method":"approle","name":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995" payload := strings.NewReader("{\n \"auth_method\": \"approle\",\n \"name\": \"\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"auth_method\": \"approle\",\n \"name\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"auth_method\": \"approle\",\n \"name\": \"\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995', [ 'body' => '{ "auth_method": "approle", "name": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"auth_method\": \"approle\",\n \"name\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "auth_method": "approle", "name": "" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/stores/019f1e4b-3edd-72cf-b90e-26864ba2f283/identities?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get application identity url: https://ibee.ai/docs/api-reference/secret-store/get-secret-identity last_updated: 2026-10-25 --- # Get application identity GET https://api.ibee.ai/v1/secret-store/identities/{identity_id} Gets one application identity without credentials. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identity returned successfully. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete application identity url: https://ibee.ai/docs/api-reference/secret-store/delete-secret-identity last_updated: 2026-10-25 --- # Delete application identity DELETE https://api.ibee.ai/v1/secret-store/identities/{identity_id} Permanently removes the identity, its scopes, role, policy, and sessions. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X DELETE "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/delete-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identity deleted successfully. - `status` (enum, required) — - `deleted`: the identity was removed. - `revoked`: its active credentials were revoked. - Allowed values: `deleted`, `revoked` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "status": "deleted" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update application identity url: https://ibee.ai/docs/api-reference/secret-store/update-secret-identity last_updated: 2026-10-25 --- # Update application identity PATCH https://api.ibee.ai/v1/secret-store/identities/{identity_id} Content-Type: application/json Updates the token policy mode. Identity names cannot be changed after creation. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X PATCH "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"token_policy_mode": "read_only"}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/update-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateSecretIdentityRequest. - `token_policy_mode` (enum, optional) — Updating the mode also aligns every existing scope and revokes active sessions. - Allowed values: `read_only`, `read_write` ## Response ### 200 Identity updated successfully. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "token_policy_mode": "read_only" } ``` **Response** ```json { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123" querystring = {"workspace_id":"710995"} payload = { "token_policy_mode": "read_only" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"token_policy_mode":"read_only"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995" payload := strings.NewReader("{\n \"token_policy_mode\": \"read_only\"\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"token_policy_mode\": \"read_only\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"token_policy_mode\": \"read_only\"\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995', [ 'body' => '{ "token_policy_mode": "read_only" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"token_policy_mode\": \"read_only\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["token_policy_mode": "read_only"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Disable application identity url: https://ibee.ai/docs/api-reference/secret-store/disable-secret-identity last_updated: 2026-10-25 --- # Disable application identity POST https://api.ibee.ai/v1/secret-store/identities/{identity_id}/disable Disables an identity and revokes its active sessions. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X POST "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/disable?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/disable-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identity disabled successfully. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/disable" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/disable?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Enable application identity url: https://ibee.ai/docs/api-reference/secret-store/enable-secret-identity last_updated: 2026-10-25 --- # Enable application identity POST https://api.ibee.ai/v1/secret-store/identities/{identity_id}/enable Re-enables a disabled identity. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X POST "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/enable?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/enable-secret-identity ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identity enabled successfully. - `id` (string, required) — Unique ID of the identity. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `name` (string, required) — Display name of the identity. - `auth_method` (enum, required) — - `approle`: authenticates with a role ID and secret ID. - `kubernetes`: authenticates with a Kubernetes service account token. - Allowed values: `approle`, `kubernetes` - `openbao_role_name` (string, required) — Name of the backend authentication role created for the identity. - `status` (enum, required) — - `active`: can authenticate. - `disabled`: authentication is refused. - Allowed values: `active`, `disabled` - `token_policy_mode` (enum, required) — Access mode of the identity's tokens. - `read_only` - `read_write` - Allowed values: `read_only`, `read_write` - `created_at` (datetime, required) — When the record was created (ISO 8601). - `updated_at` (datetime, required) — When the record was last changed (ISO 8601). - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace of the service account, for `kubernetes` identities. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account name, for `kubernetes` identities. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "id": "", "organization_id": "", "workspace_id": "", "name": "", "auth_method": "approle", "openbao_role_name": "", "status": "active", "token_policy_mode": "read_only", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/enable" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/enable?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get application identity access details url: https://ibee.ai/docs/api-reference/secret-store/get-secret-identity-access last_updated: 2026-10-25 --- # Get application identity access details GET https://api.ibee.ai/v1/secret-store/identities/{identity_id}/access Returns Kubernetes binding details or generates fresh AppRole credentials. Treat secret_id as sensitive. Each call for an AppRole identity mints a new credential, so the gateway treats this GET as a write. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/access?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/get-secret-identity-access ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Access details returned successfully. - `identity_id` (string, required) — ID of the identity. - `auth_method` (enum, required) — - `approle` - `kubernetes` - Allowed values: `approle`, `kubernetes` - `role_id` (string, optional, nullable) — AppRole role ID. - `secret_id` (string, optional, nullable) — Fresh AppRole secret ID. Treat this value as sensitive. - `secret_id_accessor` (string, optional, nullable) — Accessor of the issued AppRole secret ID, usable to revoke it. - `openbao_role_name` (string, optional, nullable) — Kubernetes authentication role. - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace bound to the identity, for `kubernetes`. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account bound to the identity, for `kubernetes`. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "identity_id": "", "auth_method": "approle", "role_id": "", "secret_id": "", "secret_id_accessor": "", "openbao_role_name": "", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/access" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/access?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Rotate AppRole secret ID url: https://ibee.ai/docs/api-reference/secret-store/rotate-secret-identity-secret-id last_updated: 2026-10-25 --- # Rotate AppRole secret ID POST https://api.ibee.ai/v1/secret-store/identities/{identity_id}/rotate-secret-id Generates fresh AppRole credentials. Available only for AppRole identities. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X POST "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/rotate-secret-id?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/rotate-secret-identity-secret-id ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Fresh AppRole access details returned successfully. - `identity_id` (string, required) — ID of the identity. - `auth_method` (enum, required) — - `approle` - `kubernetes` - Allowed values: `approle`, `kubernetes` - `role_id` (string, optional, nullable) — AppRole role ID. - `secret_id` (string, optional, nullable) — Fresh AppRole secret ID. Treat this value as sensitive. - `secret_id_accessor` (string, optional, nullable) — Accessor of the issued AppRole secret ID, usable to revoke it. - `openbao_role_name` (string, optional, nullable) — Kubernetes authentication role. - `k8s_namespace` (string, optional, nullable) — Kubernetes namespace bound to the identity, for `kubernetes`. - `k8s_service_account` (string, optional, nullable) — Kubernetes service account bound to the identity, for `kubernetes`. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "identity_id": "", "auth_method": "approle", "role_id": "", "secret_id": "", "secret_id_accessor": "", "openbao_role_name": "", "k8s_namespace": "", "k8s_service_account": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/rotate-secret-id?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Revoke application identity sessions url: https://ibee.ai/docs/api-reference/secret-store/revoke-secret-identity-sessions last_updated: 2026-10-25 --- # Revoke application identity sessions POST https://api.ibee.ai/v1/secret-store/identities/{identity_id}/revoke Revokes active sessions without deleting or disabling the identity. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X POST "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/revoke?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/revoke-secret-identity-sessions ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Identity sessions revoked successfully. - `status` (enum, required) — - `deleted`: the identity was removed. - `revoked`: its active credentials were revoked. - Allowed values: `deleted`, `revoked` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "status": "deleted" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/revoke?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List application identity scopes url: https://ibee.ai/docs/api-reference/secret-store/list-secret-identity-scopes last_updated: 2026-10-25 --- # List application identity scopes GET https://api.ibee.ai/v1/secret-store/identities/{identity_id}/scopes Lists the stores and permissions available to an identity. Requires scope: secret-store.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/scopes?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/list-secret-identity-scopes ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Scopes returned successfully. - `scopes` (list of SecretIdentityScope, required) — Scopes returned. - `total` (integer, required) — Total number of scopes. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### SecretIdentityScope An identity's access grant to one store. - `id` (string, required) — Unique ID of the scope. - `identity_id` (string, required) — Identity the scope belongs to. - `scope_type` (string, required) — Always `store`: scopes are granted per store. - `store_id` (string, required) — Store the scope grants access to. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `access_mode` (enum, required) — - `read_only`: the identity can read secrets in the store. - `read_write`: the identity can also create and update them. - Allowed values: `read_only`, `read_write` - `allow_version_read` (boolean, required) — Whether the identity may read non-current versions of a secret. - `allow_rollback` (boolean, required) — Whether the identity may roll a secret back to an earlier version. - `allow_destroy` (boolean, required) — Whether the identity may destroy secret versions. - `created_at` (datetime, required) — When the scope was created (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "scopes": [ { "id": "", "identity_id": "", "scope_type": "", "store_id": "", "organization_id": "", "workspace_id": "", "access_mode": "read_only", "allow_version_read": true, "allow_rollback": true, "allow_destroy": true, "created_at": "2026-10-25T12:00:00Z" } ], "total": 1 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Add application identity scope url: https://ibee.ai/docs/api-reference/secret-store/create-secret-identity-scope last_updated: 2026-10-25 --- # Add application identity scope POST https://api.ibee.ai/v1/secret-store/identities/{identity_id}/scopes Content-Type: application/json Grants an identity access to another store. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # IDENTITY_ID: Secret Store application identity ID curl -X POST "https://api.ibee.ai/v1/secret-store/identities/$IDENTITY_ID/scopes?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"store_id": ""}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/create-secret-identity-scope ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `identity_id` (string, required) — Secret Store application identity ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateSecretIdentityScopeRequest. - `store_id` (string, required) — Store the identity gets access to. - `access_mode` (enum, optional, default: read_only) — - `read_only`: the identity can read secrets in the store. - `read_write`: the identity can also create and update them. Default `read_only`. - Allowed values: `read_only`, `read_write` - `allow_version_read` (boolean, optional, default: true) — Whether the identity may read non-current versions of a secret. - `allow_rollback` (boolean, optional, default: false) — Whether the identity may roll a secret back to an earlier version. - `allow_destroy` (boolean, optional, default: false) — Whether the identity may destroy secret versions. ## Response ### 201 Scope created successfully. - `id` (string, required) — Unique ID of the scope. - `identity_id` (string, required) — Identity the scope belongs to. - `scope_type` (string, required) — Always `store`: scopes are granted per store. - `store_id` (string, required) — Store the scope grants access to. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `access_mode` (enum, required) — - `read_only`: the identity can read secrets in the store. - `read_write`: the identity can also create and update them. - Allowed values: `read_only`, `read_write` - `allow_version_read` (boolean, required) — Whether the identity may read non-current versions of a secret. - `allow_rollback` (boolean, required) — Whether the identity may roll a secret back to an earlier version. - `allow_destroy` (boolean, required) — Whether the identity may destroy secret versions. - `created_at` (datetime, required) — When the scope was created (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "store_id": "" } ``` **Response** ```json { "id": "", "identity_id": "", "scope_type": "", "store_id": "", "organization_id": "", "workspace_id": "", "access_mode": "read_only", "allow_version_read": true, "allow_rollback": true, "allow_destroy": true, "created_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes" querystring = {"workspace_id":"710995"} payload = { "store_id": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"store_id":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995" payload := strings.NewReader("{\n \"store_id\": \"\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"store_id\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"store_id\": \"\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995', [ 'body' => '{ "store_id": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"store_id\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["store_id": ""] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/identities/identity_123/scopes?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete application identity scope url: https://ibee.ai/docs/api-reference/secret-store/delete-secret-identity-scope last_updated: 2026-10-25 --- # Delete application identity scope DELETE https://api.ibee.ai/v1/secret-store/scopes/{scope_id} Removes a store permission from an identity. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SCOPE_ID: Secret Store identity scope ID curl -X DELETE "https://api.ibee.ai/v1/secret-store/scopes/$SCOPE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/secret-store/delete-secret-identity-scope ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `scope_id` (string, required) — Secret Store identity scope ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Scope deleted successfully. - `status` (enum, required) — - `deleted`: the identity was removed. - `revoked`: its active credentials were revoked. - Allowed values: `deleted`, `revoked` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "status": "deleted" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/scopes/scope_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update application identity scope url: https://ibee.ai/docs/api-reference/secret-store/update-secret-identity-scope last_updated: 2026-10-25 --- # Update application identity scope PATCH https://api.ibee.ai/v1/secret-store/scopes/{scope_id} Content-Type: application/json Updates store access and version permissions for a scope. Requires scope: secret-store.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # SCOPE_ID: Secret Store identity scope ID curl -X PATCH "https://api.ibee.ai/v1/secret-store/scopes/$SCOPE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"access_mode": "read_only", "allow_version_read": true}' ``` Reference: https://ibee.ai/docs/api-reference/secret-store/update-secret-identity-scope ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `scope_id` (string, required) — Secret Store identity scope ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateSecretIdentityScopeRequest. - `access_mode` (enum, optional) — - `read_only`: the identity can read secrets in the store. - `read_write`: the identity can also create and update them. - Allowed values: `read_only`, `read_write` - `allow_version_read` (boolean, optional) — Whether the identity may read non-current versions of a secret. - `allow_rollback` (boolean, optional) — Whether the identity may roll a secret back to an earlier version. - `allow_destroy` (boolean, optional) — Whether the identity may destroy secret versions. ## Response ### 200 Scope updated successfully. - `id` (string, required) — Unique ID of the scope. - `identity_id` (string, required) — Identity the scope belongs to. - `scope_type` (string, required) — Always `store`: scopes are granted per store. - `store_id` (string, required) — Store the scope grants access to. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `access_mode` (enum, required) — - `read_only`: the identity can read secrets in the store. - `read_write`: the identity can also create and update them. - Allowed values: `read_only`, `read_write` - `allow_version_read` (boolean, required) — Whether the identity may read non-current versions of a secret. - `allow_rollback` (boolean, required) — Whether the identity may roll a secret back to an earlier version. - `allow_destroy` (boolean, required) — Whether the identity may destroy secret versions. - `created_at` (datetime, required) — When the scope was created (ISO 8601). ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "access_mode": "read_only", "allow_version_read": true } ``` **Response** ```json { "id": "", "identity_id": "", "scope_type": "", "store_id": "", "organization_id": "", "workspace_id": "", "access_mode": "read_only", "allow_version_read": true, "allow_rollback": true, "allow_destroy": true, "created_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/secret-store/scopes/scope_123" querystring = {"workspace_id":"710995"} payload = { "access_mode": "read_only", "allow_version_read": True } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"access_mode":"read_only","allow_version_read":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995" payload := strings.NewReader("{\n \"access_mode\": \"read_only\",\n \"allow_version_read\": true\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"access_mode\": \"read_only\",\n \"allow_version_read\": true\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"access_mode\": \"read_only\",\n \"allow_version_read\": true\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995', [ 'body' => '{ "access_mode": "read_only", "allow_version_read": true }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"access_mode\": \"read_only\",\n \"allow_version_read\": true\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "access_mode": "read_only", "allow_version_read": true ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/secret-store/scopes/scope_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List buckets url: https://ibee.ai/docs/api-reference/object-storage/list-buckets last_updated: 2026-10-25 --- # List buckets GET https://api.ibee.ai/v1/object-storage/buckets Lists object storage buckets in a workspace. Requires scope: object-storage.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/list-buckets ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. - `limit` (integer, optional, default: 100) — Maximum number of buckets to return. - `continuation_token` (string, optional) — Pagination token from the previous response. ## Response ### 200 Buckets returned successfully. - `buckets` (list of Bucket, optional) — Buckets on this page. - `is_truncated` (boolean, optional) — True when more buckets exist beyond this page. - `next_continuation_token` (string, optional, nullable) — Token to pass as `continuation_token` to fetch the next page; null on the last page. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### Bucket An object storage bucket. Read and list responses carry the usage counters `object_count` and `total_size`; the create response omits them because usage is only measured once the bucket exists. - `name` (string, required) — Unique bucket name within the workspace. - `is_public` (boolean, required) — Whether the bucket allows unauthenticated read access. - `region` (string, required, nullable) — Object storage region the bucket lives in. - `plan` (string, required, nullable) — Storage plan billed for the bucket. - `status` (string, required, nullable) — Current bucket status. - `site_id` (string, required, nullable) — Identifier of the site holding the bucket. Placement is managed internally. - `site_name` (string, required, nullable) — Human-readable name of the site holding the bucket. - `bucket_lock_enabled` (boolean, required) — Whether object lock is enabled on the bucket. - `created_at` (datetime, required, nullable) — When the bucket was created (ISO 8601). - `updated_at` (datetime, required, nullable) — When the bucket settings were last changed (ISO 8601). - `object_count` (integer, optional) — Number of objects stored in the bucket. Returned by the read and list endpoints only. - `total_size` (integer, optional) — Total size in bytes of the objects stored in the bucket. Returned by the read and list endpoints only. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "buckets": [ { "name": "production-assets", "is_public": false, "region": "in-south-2", "plan": "standard", "status": "active", "site_id": "3", "site_name": "Hyderabad", "bucket_lock_enabled": false, "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "object_count": 42, "total_size": 1048576 } ], "is_truncated": false, "next_continuation_token": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/buckets" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create bucket url: https://ibee.ai/docs/api-reference/object-storage/create-bucket last_updated: 2026-10-25 --- # Create bucket POST https://api.ibee.ai/v1/object-storage/buckets Content-Type: application/json Creates an object storage bucket. `region` is required and must match an Object Storage region identifier configured for the target environment. Do not send a compute `site_id`. Requires scope: object-storage.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl -X POST "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "production-assets", "region": "in-south-2"}' ``` Reference: https://ibee.ai/docs/api-reference/object-storage/create-bucket ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateBucketRequest. - `name` (string, required) — Unique bucket name within the workspace. - `region` (string, required) — Required Object Storage region identifier. This must match a region configured for the target environment; it is not a compute `site_id` or display name. - `is_public` (boolean, optional, default: false) — Whether the bucket allows unauthenticated read access. - `object_lock_enabled` (boolean, optional, default: false) — Must be `true` when `default_retention` is provided. - `default_retention` (DefaultRetention, optional) — Optional default object retention. Supply exactly one of `days` or `years`, and set `object_lock_enabled` to `true`. - `tags` (list of string, optional) — Optional tags stored alongside bucket metadata. ## Response ### 201 Bucket created successfully. - `name` (string, required) — Unique bucket name within the workspace. - `is_public` (boolean, required) — Whether the bucket allows unauthenticated read access. - `region` (string, required, nullable) — Object storage region the bucket lives in. - `plan` (string, required, nullable) — Storage plan billed for the bucket. - `status` (string, required, nullable) — Current bucket status. - `site_id` (string, required, nullable) — Identifier of the site holding the bucket. Placement is managed internally. - `site_name` (string, required, nullable) — Human-readable name of the site holding the bucket. - `bucket_lock_enabled` (boolean, required) — Whether object lock is enabled on the bucket. - `created_at` (datetime, required, nullable) — When the bucket was created (ISO 8601). - `updated_at` (datetime, required, nullable) — When the bucket settings were last changed (ISO 8601). - `object_count` (integer, optional) — Number of objects stored in the bucket. Returned by the read and list endpoints only. - `total_size` (integer, optional) — Total size in bytes of the objects stored in the bucket. Returned by the read and list endpoints only. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 402 Payment Required Error Billing refused the request (`billing_denied`). `billing_reason` carries Billing's reason unchanged, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` (a plan limit) or `resource_usage_unavailable` (Billing could not count usage). `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` identify the decision. Nothing is provisioned; resolve the reason and retry with the same idempotency key where supported. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### DefaultRetention Optional default object retention. Supply exactly one of `days` or `years`, and set `object_lock_enabled` to `true`. - `mode` (enum, required) — - `GOVERNANCE`: retention can be overridden by users with the bypass permission. - `COMPLIANCE`: retention cannot be shortened or removed until it expires. - Allowed values: `GOVERNANCE`, `COMPLIANCE` - `days` (integer, optional, nullable) — Retention period in days (1-36500). Supply either `days` or `years`. - `years` (integer, optional, nullable) — Retention period in years (1-100). Supply either `days` or `years`. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "production-assets", "region": "in-south-2" } ``` **Response** ```json { "name": "production-assets", "is_public": false, "region": "in-south-2", "plan": "standard", "status": "active", "site_id": "3", "site_name": "Hyderabad", "bucket_lock_enabled": false, "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "object_count": 42, "total_size": 1048576 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/buckets" querystring = {"workspace_id":"710995"} payload = { "name": "production-assets", "region": "in-south-2" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"production-assets","region":"in-south-2"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"production-assets\",\n \"region\": \"in-south-2\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"production-assets\",\n \"region\": \"in-south-2\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"production-assets\",\n \"region\": \"in-south-2\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995', [ 'body' => '{ "name": "production-assets", "region": "in-south-2" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"production-assets\",\n \"region\": \"in-south-2\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "production-assets", "region": "in-south-2" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get bucket url: https://ibee.ai/docs/api-reference/object-storage/get-bucket last_updated: 2026-10-25 --- # Get bucket GET https://api.ibee.ai/v1/object-storage/buckets/{bucket_name} Returns bucket configuration and usage statistics. Requires scope: object-storage.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # BUCKET_NAME: Logical bucket name curl "https://api.ibee.ai/v1/object-storage/buckets/$BUCKET_NAME?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/get-bucket ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `bucket_name` (string, required) — Logical bucket name. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Bucket returned successfully. - `name` (string, required) — Unique bucket name within the workspace. - `is_public` (boolean, required) — Whether the bucket allows unauthenticated read access. - `region` (string, required, nullable) — Object storage region the bucket lives in. - `plan` (string, required, nullable) — Storage plan billed for the bucket. - `status` (string, required, nullable) — Current bucket status. - `site_id` (string, required, nullable) — Identifier of the site holding the bucket. Placement is managed internally. - `site_name` (string, required, nullable) — Human-readable name of the site holding the bucket. - `bucket_lock_enabled` (boolean, required) — Whether object lock is enabled on the bucket. - `created_at` (datetime, required, nullable) — When the bucket was created (ISO 8601). - `updated_at` (datetime, required, nullable) — When the bucket settings were last changed (ISO 8601). - `object_count` (integer, optional) — Number of objects stored in the bucket. Returned by the read and list endpoints only. - `total_size` (integer, optional) — Total size in bytes of the objects stored in the bucket. Returned by the read and list endpoints only. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "name": "production-assets", "is_public": false, "region": "in-south-2", "plan": "standard", "status": "active", "site_id": "3", "site_name": "Hyderabad", "bucket_lock_enabled": false, "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "object_count": 42, "total_size": 1048576 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/buckets/my-bucket" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete bucket url: https://ibee.ai/docs/api-reference/object-storage/delete-bucket last_updated: 2026-10-25 --- # Delete bucket DELETE https://api.ibee.ai/v1/object-storage/buckets/{bucket_name} Deletes a bucket and all of its contents. Requires scope: object-storage.delete. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # BUCKET_NAME: Logical bucket name curl -X DELETE "https://api.ibee.ai/v1/object-storage/buckets/$BUCKET_NAME?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/delete-bucket ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `bucket_name` (string, required) — Logical bucket name. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Bucket deleted successfully. - `detail` (string, optional) — Human-readable result. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "detail": "Deleted successfully" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/buckets/my-bucket" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update bucket settings url: https://ibee.ai/docs/api-reference/object-storage/update-bucket last_updated: 2026-10-25 --- # Update bucket settings PATCH https://api.ibee.ai/v1/object-storage/buckets/{bucket_name} Content-Type: application/json Updates mutable bucket settings. Requires scope: object-storage.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # BUCKET_NAME: Logical bucket name curl -X PATCH "https://api.ibee.ai/v1/object-storage/buckets/$BUCKET_NAME?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"is_public": true}' ``` Reference: https://ibee.ai/docs/api-reference/object-storage/update-bucket ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `bucket_name` (string, required) — Logical bucket name. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateBucketRequest. - `is_public` (boolean, required) — Whether the bucket allows unauthenticated read access. ## Response ### 200 Bucket updated successfully. - `name` (string, required) — Unique bucket name within the workspace. - `is_public` (boolean, required) — Whether the bucket allows unauthenticated read access. - `region` (string, required, nullable) — Object storage region the bucket lives in. - `plan` (string, required, nullable) — Storage plan billed for the bucket. - `status` (string, required, nullable) — Current bucket status. - `site_id` (string, required, nullable) — Identifier of the site holding the bucket. Placement is managed internally. - `site_name` (string, required, nullable) — Human-readable name of the site holding the bucket. - `bucket_lock_enabled` (boolean, required) — Whether object lock is enabled on the bucket. - `created_at` (datetime, required, nullable) — When the bucket was created (ISO 8601). - `updated_at` (datetime, required, nullable) — When the bucket settings were last changed (ISO 8601). - `object_count` (integer, optional) — Number of objects stored in the bucket. Returned by the read and list endpoints only. - `total_size` (integer, optional) — Total size in bytes of the objects stored in the bucket. Returned by the read and list endpoints only. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "is_public": true } ``` **Response** ```json { "name": "production-assets", "is_public": false, "region": "in-south-2", "plan": "standard", "status": "active", "site_id": "3", "site_name": "Hyderabad", "bucket_lock_enabled": false, "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "object_count": 42, "total_size": 1048576 } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/buckets/my-bucket" querystring = {"workspace_id":"710995"} payload = { "is_public": True } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"is_public":true}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995" payload := strings.NewReader("{\n \"is_public\": true\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"is_public\": true\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"is_public\": true\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995', [ 'body' => '{ "is_public": true }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"is_public\": true\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["is_public": true] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/buckets/my-bucket?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List S3 credentials url: https://ibee.ai/docs/api-reference/object-storage/list-s-3-credentials last_updated: 2026-10-25 --- # List S3 credentials GET https://api.ibee.ai/v1/object-storage/credentials Lists S3-compatible credentials without secret keys. Requires scope: object-storage.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/list-s-3-credentials ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Credentials returned successfully. - `credentials` (list of S3Credential, required) — Key pairs returned. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### S3Credential An S3 access key pair. The secret key is returned only when the pair is created. - `access_key_id` (string, required) — S3 access key ID. - `name` (string, required) — Display name of the key pair. - `status` (enum, required) — - `active`: usable. - `revoked`: no longer accepted. - Allowed values: `active`, `revoked` - `created_at` (datetime, required) — When the key pair was created (ISO 8601). - `project_id` (string, optional) — Legacy identifier of the owning project. - `last_used_at` (datetime, optional, nullable) — When the key was last used to sign a request (ISO 8601); null if never. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "credentials": [ { "access_key_id": "", "name": "", "status": "active", "created_at": "2026-10-25T12:00:00Z", "project_id": "", "last_used_at": "2026-10-25T12:00:00Z" } ] } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/credentials" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create S3 credential url: https://ibee.ai/docs/api-reference/object-storage/create-s-3-credential last_updated: 2026-10-25 --- # Create S3 credential POST https://api.ibee.ai/v1/object-storage/credentials Content-Type: application/json Creates an access key pair. The secret is returned only once. Requires scope: object-storage.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl -X POST "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Default Key", "permission_type": "admin_rw"}' ``` Reference: https://ibee.ai/docs/api-reference/object-storage/create-s-3-credential ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateS3CredentialRequest. - `name` (string, optional, default: Default Key) — Display name of the key pair. Default `Default Key`. - `permission_type` (string, optional, default: admin_rw) — Permission level: `admin_rw`, `admin_ro`, `object_rw` or `object_ro`. Default `admin_rw`. - `bucket_scope` (enum, optional, default: all) — - `all`: the key may use every bucket in the workspace (default). - `specific`: only the buckets in `allowed_buckets`. - Allowed values: `all`, `specific` - `allowed_buckets` (list of string, optional) — Bucket names the key may use when `bucket_scope` is `specific`. ## Response ### 201 Credential created successfully. - `access_key_id` (string, required) — S3 access key ID. - `name` (string, required) — Display name of the key pair. - `status` (enum, required) — - `active`: usable. - `revoked`: no longer accepted. - Allowed values: `active`, `revoked` - `created_at` (datetime, required) — When the key pair was created (ISO 8601). - `secret_access_key` (string, required) — Returned once at creation time. - `project_id` (string, optional) — Legacy identifier of the owning project. - `last_used_at` (datetime, optional, nullable) — When the key was last used to sign a request (ISO 8601); null if never. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 402 Payment Required Error Billing refused the request (`billing_denied`). `billing_reason` carries Billing's reason unchanged, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` (a plan limit) or `resource_usage_unavailable` (Billing could not count usage). `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` identify the decision. Nothing is provisioned; resolve the reason and retry with the same idempotency key where supported. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "Default Key", "permission_type": "admin_rw" } ``` **Response** ```json { "access_key_id": "", "name": "", "status": "active", "created_at": "2026-10-25T12:00:00Z", "secret_access_key": "", "project_id": "", "last_used_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/credentials" querystring = {"workspace_id":"710995"} payload = { "name": "Default Key", "permission_type": "admin_rw" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"Default Key","permission_type":"admin_rw"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"Default Key\",\n \"permission_type\": \"admin_rw\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Default Key\",\n \"permission_type\": \"admin_rw\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Default Key\",\n \"permission_type\": \"admin_rw\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995', [ 'body' => '{ "name": "Default Key", "permission_type": "admin_rw" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Default Key\",\n \"permission_type\": \"admin_rw\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "Default Key", "permission_type": "admin_rw" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/credentials?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get S3 credential url: https://ibee.ai/docs/api-reference/object-storage/get-s-3-credential last_updated: 2026-10-25 --- # Get S3 credential GET https://api.ibee.ai/v1/object-storage/credentials/{access_key_id} Returns credential metadata without the secret key. Requires scope: object-storage.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # ACCESS_KEY_ID: S3 access key ID curl "https://api.ibee.ai/v1/object-storage/credentials/$ACCESS_KEY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/get-s-3-credential ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `access_key_id` (string, required) — S3 access key ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Credential returned successfully. - `access_key_id` (string, required) — S3 access key ID. - `name` (string, required) — Display name of the key pair. - `status` (enum, required) — - `active`: usable. - `revoked`: no longer accepted. - Allowed values: `active`, `revoked` - `created_at` (datetime, required) — When the key pair was created (ISO 8601). - `project_id` (string, optional) — Legacy identifier of the owning project. - `last_used_at` (datetime, optional, nullable) — When the key was last used to sign a request (ISO 8601); null if never. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "access_key_id": "", "name": "", "status": "active", "created_at": "2026-10-25T12:00:00Z", "project_id": "", "last_used_at": "2026-10-25T12:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Revoke S3 credential url: https://ibee.ai/docs/api-reference/object-storage/revoke-s-3-credential last_updated: 2026-10-25 --- # Revoke S3 credential DELETE https://api.ibee.ai/v1/object-storage/credentials/{access_key_id} Revokes a credential so it can no longer authenticate S3 requests. Requires scope: object-storage.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # ACCESS_KEY_ID: S3 access key ID curl -X DELETE "https://api.ibee.ai/v1/object-storage/credentials/$ACCESS_KEY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/object-storage/revoke-s-3-credential ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `access_key_id` (string, required) — S3 access key ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Credential revoked successfully. - `success` (boolean, required) — True when the key pair was revoked. - `message` (string, required) — Human-readable result. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "success": true, "message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/object-storage/credentials/AKIAIOSFODNN7EXAMPLE?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List VPC-enabled sites url: https://ibee.ai/docs/api-reference/vpcs/list-networking-sites last_updated: 2026-10-25 --- # List VPC-enabled sites GET https://api.ibee.ai/v1/networking/sites Lists the site IDs accepted by VPC and Reserved IP creation. Use only entries where `available` is `true`. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/networking/sites?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-networking-sites ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Site availability returned successfully. - `list of NetworkingSite` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NetworkingSite A site where VPCs and Reserved IPs can be created. - `site_id` (string, required) — Canonical opaque site identifier accepted by VPC and Reserved IP creation. Copy it exactly; do not substitute a region or site name. - `site_name` (string, required) — Display name of the site. - `available` (boolean, required) — Whether the site currently accepts new VPCs and reservations. - `message` (string, optional, nullable) — Why the site is unavailable, when it is. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json [ { "site_id": "68b99bd78a8eda32ff3f16ea", "site_name": "", "available": true, "message": "" } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/sites" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/sites?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/sites?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/sites?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/sites?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/sites?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/sites?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/sites?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List VPCs url: https://ibee.ai/docs/api-reference/vpcs/list-vpcs last_updated: 2026-10-25 --- # List VPCs GET https://api.ibee.ai/v1/networking/vpcs Lists VPCs in the selected workspace. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/networking/vpcs?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-vpcs ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. - `site_id` (string, optional) — Optional exact site filter. Copy `site_id` from `GET /networking/sites`. ## Response ### 200 VPCs returned successfully. - `list of VpcSummary` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### VpcSummary A VPC with its attached-node count and NAT gateway pricing. - `vpc_id` (string, required) — Unique ID of the VPC. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `site_id` (string, required) — Site the VPC lives at. - `name` (string, required) — Display name of the VPC. - `cidr` (string, required) — IPv4 CIDR of the VPC. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `connectivity_type` (enum, required) — The VPC's internet model. - `public`: instances may have dedicated public IPs. - `nat_gateway`: private VPC with managed outbound NAT; dedicated public IPs are not allowed. - `private`: no managed internet path. - Allowed values: `public`, `private`, `nat_gateway` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `account_id` (string, optional) — Legacy alias of `organization_id`. - `description` (string, optional) — Description of the VPC. - `region` (string, optional, nullable) — Region label stored with the VPC, when set. - `is_default` (boolean, optional) — Whether this is the workspace's default VPC. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. - `node_count` (integer, optional) — Number of VMs attached to the VPC. - `nat_pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ## Examples **Response** ```json [ { "vpc_id": "", "organization_id": "", "workspace_id": "", "site_id": "", "name": "", "cidr": "", "status": "provisioning", "connectivity_type": "public", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "account_id": "", "description": "", "region": "", "is_default": true, "error_message": "", "node_count": 1, "nat_pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false } } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create a VPC url: https://ibee.ai/docs/api-reference/vpcs/create-vpc last_updated: 2026-10-25 --- # Create a VPC POST https://api.ibee.ai/v1/networking/vpcs Content-Type: application/json Creates an isolated virtual network. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl -X POST "https://api.ibee.ai/v1/networking/vpcs?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "", "site_id": "68b99bd78a8eda32ff3f16ea"}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/create-vpc ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateVpcRequest. - `name` (string, required) — Display name of the VPC. - `site_id` (string, required) — Required network placement site. Copy `site_id` from `GET /networking/sites` and choose an entry where `available` is `true`. Do not use a region name. - `description` (string, optional, default: ) — Optional description. - `region` (string, optional, nullable) — Optional region label stored with the VPC. - `cidr` (string, optional, nullable) — RFC1918 IPv4 CIDR with a prefix between /22 and /28. - `auto_cidr` (boolean, optional, default: true) — Let the service choose a free CIDR when `cidr` is omitted. Default true. - `create_default_subnet` (boolean, optional, default: true) — Create a first subnet together with the VPC. Default true. - `default_subnet_cidr` (string, optional, nullable) — CIDR for that first subnet; chosen automatically when omitted. - `is_default` (boolean, optional, default: false) — Mark the VPC as the workspace's default VPC. Default false. - `connectivity_type` (enum, optional, default: public) — The VPC's internet model; the server uses `public` when this is omitted. `public` keeps dedicated public IPs available to its VMs. `private` has no shared public edge, but a VM can still be given a Reserved IP. `nat_gateway` is a private VPC with managed outbound NAT and refuses dedicated public IPs. - Allowed values: `public`, `private`, `nat_gateway` ## Response ### 201 VPC created successfully. - `vpc_id` (string, required) — Unique ID of the VPC. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `site_id` (string, required) — Site the VPC lives at. - `name` (string, required) — Display name of the VPC. - `cidr` (string, required) — IPv4 CIDR of the VPC. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `connectivity_type` (enum, required) — The VPC's internet model. - `public`: instances may have dedicated public IPs. - `nat_gateway`: private VPC with managed outbound NAT; dedicated public IPs are not allowed. - `private`: no managed internet path. - Allowed values: `public`, `private`, `nat_gateway` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `account_id` (string, optional) — Legacy alias of `organization_id`. - `description` (string, optional) — Description of the VPC. - `region` (string, optional, nullable) — Region label stored with the VPC, when set. - `is_default` (boolean, optional) — Whether this is the workspace's default VPC. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. - `node_count` (integer, optional) — Number of VMs attached to the VPC. - `nat_pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `subnets` (list of Subnet, optional) — Subnets in the VPC. - `nat_gateways` (list of NatGateway, optional) — NAT gateways in the VPC. - `attached_nodes` (list of VpcAttachedNode, optional) — VMs attached to the VPC. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ### Subnet A subnet of a VPC. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### NatGateway A managed NAT gateway that gives a VPC's VMs outbound internet access through one public address. - `nat_gateway_id` (string, required) — Unique ID of the gateway. - `vpc_id` (string, required) — VPC the gateway serves. - `site_id` (string, required) — Site the gateway lives at. - `name` (string, required) — Display name of the gateway. - `public_ip_id` (string, required) — ID of the public IP the gateway uses. - `public_ip` (string, required) — Public IPv4 address of the gateway. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### VpcAttachedNode Summary of a VM attached to a VPC. - `allocation_id` (string, optional) — ID of the attachment. - `vm_id` (string, optional) — ID of the attached VM. - `subnet_id` (string, optional) — Subnet the VM is attached to. - `private_ip` (string, optional) — Private IPv4 address assigned to the VM. - `connectivity` (enum, optional) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. - Allowed values: `private`, `public_ip`, `nat` - `public_ip` (string, optional, nullable) — Reserved IP address attached to the VM, when `connectivity` is `public_ip`. - `nat_public_ip` (string, optional, nullable) — Public address of the NAT gateway used, when `connectivity` is `nat`. - `status` (string, optional) — Attachment state: `reserved`, `attaching`, `attached`, `moving`, `detaching` or `releasing`. - `attached_at` (datetime, optional) — When the VM was attached (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "", "site_id": "68b99bd78a8eda32ff3f16ea" } ``` **Response** ```json { "vpc_id": "", "organization_id": "", "workspace_id": "", "site_id": "", "name": "", "cidr": "", "status": "provisioning", "connectivity_type": "public", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "account_id": "", "description": "", "region": "", "is_default": true, "error_message": "", "node_count": 1, "nat_pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "subnets": [ { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ], "nat_gateways": [ { "nat_gateway_id": "", "vpc_id": "", "site_id": "", "name": "", "public_ip_id": "", "public_ip": "", "status": "provisioning", "subnet_id": "", "organization_id": "", "workspace_id": "", "pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "error_message": "" } ], "attached_nodes": [ { "allocation_id": "", "vm_id": "", "subnet_id": "", "private_ip": "", "connectivity": "private", "public_ip": "", "nat_public_ip": "", "status": "", "attached_at": "2026-10-25T12:00:00Z" } ] } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs" querystring = {"workspace_id":"710995"} payload = { "name": "", "site_id": "68b99bd78a8eda32ff3f16ea" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"","site_id":"68b99bd78a8eda32ff3f16ea"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\",\n \"site_id\": \"68b99bd78a8eda32ff3f16ea\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\",\n \"site_id\": \"68b99bd78a8eda32ff3f16ea\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\",\n \"site_id\": \"68b99bd78a8eda32ff3f16ea\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995', [ 'body' => '{ "name": "", "site_id": "68b99bd78a8eda32ff3f16ea" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\",\n \"site_id\": \"68b99bd78a8eda32ff3f16ea\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "", "site_id": "68b99bd78a8eda32ff3f16ea" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get a VPC url: https://ibee.ai/docs/api-reference/vpcs/get-vpc last_updated: 2026-10-25 --- # Get a VPC GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id} Returns a VPC and its subnets, NAT gateways, and attached nodes. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/get-vpc ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 VPC returned successfully. - `vpc_id` (string, required) — Unique ID of the VPC. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `site_id` (string, required) — Site the VPC lives at. - `name` (string, required) — Display name of the VPC. - `cidr` (string, required) — IPv4 CIDR of the VPC. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `connectivity_type` (enum, required) — The VPC's internet model. - `public`: instances may have dedicated public IPs. - `nat_gateway`: private VPC with managed outbound NAT; dedicated public IPs are not allowed. - `private`: no managed internet path. - Allowed values: `public`, `private`, `nat_gateway` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `account_id` (string, optional) — Legacy alias of `organization_id`. - `description` (string, optional) — Description of the VPC. - `region` (string, optional, nullable) — Region label stored with the VPC, when set. - `is_default` (boolean, optional) — Whether this is the workspace's default VPC. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. - `node_count` (integer, optional) — Number of VMs attached to the VPC. - `nat_pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `subnets` (list of Subnet, optional) — Subnets in the VPC. - `nat_gateways` (list of NatGateway, optional) — NAT gateways in the VPC. - `attached_nodes` (list of VpcAttachedNode, optional) — VMs attached to the VPC. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ### Subnet A subnet of a VPC. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### NatGateway A managed NAT gateway that gives a VPC's VMs outbound internet access through one public address. - `nat_gateway_id` (string, required) — Unique ID of the gateway. - `vpc_id` (string, required) — VPC the gateway serves. - `site_id` (string, required) — Site the gateway lives at. - `name` (string, required) — Display name of the gateway. - `public_ip_id` (string, required) — ID of the public IP the gateway uses. - `public_ip` (string, required) — Public IPv4 address of the gateway. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### VpcAttachedNode Summary of a VM attached to a VPC. - `allocation_id` (string, optional) — ID of the attachment. - `vm_id` (string, optional) — ID of the attached VM. - `subnet_id` (string, optional) — Subnet the VM is attached to. - `private_ip` (string, optional) — Private IPv4 address assigned to the VM. - `connectivity` (enum, optional) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. - Allowed values: `private`, `public_ip`, `nat` - `public_ip` (string, optional, nullable) — Reserved IP address attached to the VM, when `connectivity` is `public_ip`. - `nat_public_ip` (string, optional, nullable) — Public address of the NAT gateway used, when `connectivity` is `nat`. - `status` (string, optional) — Attachment state: `reserved`, `attaching`, `attached`, `moving`, `detaching` or `releasing`. - `attached_at` (datetime, optional) — When the VM was attached (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "vpc_id": "", "organization_id": "", "workspace_id": "", "site_id": "", "name": "", "cidr": "", "status": "provisioning", "connectivity_type": "public", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "account_id": "", "description": "", "region": "", "is_default": true, "error_message": "", "node_count": 1, "nat_pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "subnets": [ { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ], "nat_gateways": [ { "nat_gateway_id": "", "vpc_id": "", "site_id": "", "name": "", "public_ip_id": "", "public_ip": "", "status": "provisioning", "subnet_id": "", "organization_id": "", "workspace_id": "", "pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "error_message": "" } ], "attached_nodes": [ { "allocation_id": "", "vm_id": "", "subnet_id": "", "private_ip": "", "connectivity": "private", "public_ip": "", "nat_public_ip": "", "status": "", "attached_at": "2026-10-25T12:00:00Z" } ] } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete a VPC url: https://ibee.ai/docs/api-reference/vpcs/delete-vpc last_updated: 2026-10-25 --- # Delete a VPC DELETE https://api.ibee.ai/v1/networking/vpcs/{vpc_id} Deletes an empty VPC. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl -X DELETE "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/delete-vpc ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 204 VPC deleted successfully. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update a VPC url: https://ibee.ai/docs/api-reference/vpcs/update-vpc last_updated: 2026-10-25 --- # Update a VPC PATCH https://api.ibee.ai/v1/networking/vpcs/{vpc_id} Content-Type: application/json Updates mutable VPC metadata. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl -X PATCH "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "", "description": ""}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/update-vpc ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateVpcRequest. - `name` (string, optional) — New display name. - `description` (string, optional) — New description. ## Response ### 200 VPC updated successfully. - `vpc_id` (string, required) — Unique ID of the VPC. - `organization_id` (string, required) — ID of the owning organization. - `workspace_id` (string, required) — ID of the owning workspace. - `site_id` (string, required) — Site the VPC lives at. - `name` (string, required) — Display name of the VPC. - `cidr` (string, required) — IPv4 CIDR of the VPC. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `connectivity_type` (enum, required) — The VPC's internet model. - `public`: instances may have dedicated public IPs. - `nat_gateway`: private VPC with managed outbound NAT; dedicated public IPs are not allowed. - `private`: no managed internet path. - Allowed values: `public`, `private`, `nat_gateway` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `account_id` (string, optional) — Legacy alias of `organization_id`. - `description` (string, optional) — Description of the VPC. - `region` (string, optional, nullable) — Region label stored with the VPC, when set. - `is_default` (boolean, optional) — Whether this is the workspace's default VPC. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. - `node_count` (integer, optional) — Number of VMs attached to the VPC. - `nat_pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `subnets` (list of Subnet, optional) — Subnets in the VPC. - `nat_gateways` (list of NatGateway, optional) — NAT gateways in the VPC. - `attached_nodes` (list of VpcAttachedNode, optional) — VMs attached to the VPC. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ### Subnet A subnet of a VPC. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### NatGateway A managed NAT gateway that gives a VPC's VMs outbound internet access through one public address. - `nat_gateway_id` (string, required) — Unique ID of the gateway. - `vpc_id` (string, required) — VPC the gateway serves. - `site_id` (string, required) — Site the gateway lives at. - `name` (string, required) — Display name of the gateway. - `public_ip_id` (string, required) — ID of the public IP the gateway uses. - `public_ip` (string, required) — Public IPv4 address of the gateway. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### VpcAttachedNode Summary of a VM attached to a VPC. - `allocation_id` (string, optional) — ID of the attachment. - `vm_id` (string, optional) — ID of the attached VM. - `subnet_id` (string, optional) — Subnet the VM is attached to. - `private_ip` (string, optional) — Private IPv4 address assigned to the VM. - `connectivity` (enum, optional) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. - Allowed values: `private`, `public_ip`, `nat` - `public_ip` (string, optional, nullable) — Reserved IP address attached to the VM, when `connectivity` is `public_ip`. - `nat_public_ip` (string, optional, nullable) — Public address of the NAT gateway used, when `connectivity` is `nat`. - `status` (string, optional) — Attachment state: `reserved`, `attaching`, `attached`, `moving`, `detaching` or `releasing`. - `attached_at` (datetime, optional) — When the VM was attached (ISO 8601). ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "", "description": "" } ``` **Response** ```json { "vpc_id": "", "organization_id": "", "workspace_id": "", "site_id": "", "name": "", "cidr": "", "status": "provisioning", "connectivity_type": "public", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "account_id": "", "description": "", "region": "", "is_default": true, "error_message": "", "node_count": 1, "nat_pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "subnets": [ { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ], "nat_gateways": [ { "nat_gateway_id": "", "vpc_id": "", "site_id": "", "name": "", "public_ip_id": "", "public_ip": "", "status": "provisioning", "subnet_id": "", "organization_id": "", "workspace_id": "", "pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "error_message": "" } ], "attached_nodes": [ { "allocation_id": "", "vm_id": "", "subnet_id": "", "private_ip": "", "connectivity": "private", "public_ip": "", "nat_public_ip": "", "status": "", "attached_at": "2026-10-25T12:00:00Z" } ] } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123" querystring = {"workspace_id":"710995"} payload = { "name": "", "description": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"","description":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\",\n \"description\": \"\"\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\",\n \"description\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\",\n \"description\": \"\"\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995', [ 'body' => '{ "name": "", "description": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\",\n \"description\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "", "description": "" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List VPC subnets url: https://ibee.ai/docs/api-reference/vpcs/list-vpc-subnets last_updated: 2026-10-25 --- # List VPC subnets GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/subnets Lists subnets in a VPC. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/subnets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-vpc-subnets ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Subnets returned successfully. - `list of Subnet` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### Subnet A subnet of a VPC. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json [ { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [ "" ], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create a VPC subnet url: https://ibee.ai/docs/api-reference/vpcs/create-vpc-subnet last_updated: 2026-10-25 --- # Create a VPC subnet POST https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/subnets Content-Type: application/json Creates a subnet in a VPC. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl -X POST "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/subnets?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": ""}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/create-vpc-subnet ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateSubnetRequest. - `name` (string, required) — Display name of the subnet. - `cidr` (string, optional, nullable) — IPv4 CIDR inside the VPC range. Chosen automatically when omitted and `auto_cidr` is true. - `auto_cidr` (boolean, optional, default: true) — Let the service choose a free CIDR when `cidr` is omitted. Default true. - `prefix_length` (integer, optional, nullable) — Prefix length to use for an automatically chosen CIDR. - `dns` (list of string, optional, default: ["1.1.1.1","8.8.8.8"]) — DNS resolvers handed to instances in the subnet. Default `1.1.1.1` and `8.8.8.8`. ## Response ### 201 Subnet created successfully. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "" } ``` **Response** ```json { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [ "" ], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets" querystring = {"workspace_id":"710995"} payload = { "name": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995', [ 'body' => '{ "name": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": ""] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Get a VPC subnet url: https://ibee.ai/docs/api-reference/vpcs/get-vpc-subnet last_updated: 2026-10-25 --- # Get a VPC subnet GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/subnets/{subnet_id} Returns one subnet in a VPC, including its CIDR range, gateway, and DNS settings. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # SUBNET_ID: Subnet ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/subnets/$SUBNET_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/get-vpc-subnet ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `subnet_id` (string, required) — Subnet ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Subnet returned successfully. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [ "" ], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete a VPC subnet url: https://ibee.ai/docs/api-reference/vpcs/delete-vpc-subnet last_updated: 2026-10-25 --- # Delete a VPC subnet DELETE https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/subnets/{subnet_id} Deletes a subnet from a VPC. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # SUBNET_ID: Subnet ID curl -X DELETE "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/subnets/$SUBNET_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/delete-vpc-subnet ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `subnet_id` (string, required) — Subnet ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 204 Subnet deleted successfully. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update a VPC subnet url: https://ibee.ai/docs/api-reference/vpcs/update-vpc-subnet last_updated: 2026-10-25 --- # Update a VPC subnet PATCH https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/subnets/{subnet_id} Content-Type: application/json Renames a VPC subnet or changes its DNS settings. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # SUBNET_ID: Subnet ID curl -X PATCH "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/subnets/$SUBNET_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "", "dns": [""]}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/update-vpc-subnet ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `subnet_id` (string, required) — Subnet ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateSubnetRequest. - `name` (string, optional) — New display name. - `dns` (list of string, optional) — New DNS resolvers handed to instances in the subnet. ## Response ### 200 Subnet updated successfully. - `subnet_id` (string, required) — Unique ID of the subnet. - `vpc_id` (string, required) — VPC the subnet belongs to. - `site_id` (string, required) — Site the subnet lives at. - `name` (string, required) — Display name of the subnet. - `cidr` (string, required) — IPv4 CIDR of the subnet. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to instances in the subnet. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "", "dns": [ "" ] } ``` **Response** ```json { "subnet_id": "", "vpc_id": "", "site_id": "", "name": "", "cidr": "", "gateway": "", "dns": [ "" ], "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123" querystring = {"workspace_id":"710995"} payload = { "name": "", "dns": [""] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"","dns":[""]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\",\n \"dns\": [\n \"\"\n ]\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\",\n \"dns\": [\n \"\"\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\",\n \"dns\": [\n \"\"\n ]\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995', [ 'body' => '{ "name": "", "dns": [ "" ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\",\n \"dns\": [\n \"\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "", "dns": [""] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/subnets/subnet_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List nodes attached to a VPC url: https://ibee.ai/docs/api-reference/vpcs/list-vpc-nodes last_updated: 2026-10-25 --- # List nodes attached to a VPC GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nodes Lists the VMs attached to a VPC. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nodes?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-vpc-nodes ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Attached nodes returned successfully. - `list of NetworkAllocation` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NetworkAllocation A VM's attachment to a VPC subnet: its private address and how it reaches the internet. - `allocation_id` (string, required) — Unique ID of the attachment. - `vpc_id` (string, required) — VPC the VM is attached to. - `subnet_id` (string, required) — Subnet the VM is attached to. - `vm_id` (string, required) — ID of the attached VM. - `connectivity` (enum, required) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. - Allowed values: `private`, `public_ip`, `nat` - `private_ip` (string, required) — Private IPv4 address assigned to the VM. - `prefix_length` (integer, required) — Prefix length of the subnet. - `subnet_mask` (string, required) — Subnet mask in dotted-decimal form. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to the VM. - `status` (string, required) — Attachment state: `reserved`, `attaching`, `attached`, `moving`, `detaching` or `releasing`. - `public_ip_id` (string, optional, nullable) — Reserved IP attached to the allocation, when `connectivity` is `public_ip`. - `public_ip` (string, optional, nullable) — Address of that Reserved IP. - `nat_gateway_id` (string, optional, nullable) — NAT gateway used, when `connectivity` is `nat`. - `nat_public_ip` (string, optional, nullable) — Public address of that NAT gateway. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json [ { "allocation_id": "", "vpc_id": "", "subnet_id": "", "vm_id": "", "connectivity": "private", "private_ip": "", "prefix_length": 1, "subnet_mask": "", "gateway": "", "dns": [ "" ], "status": "", "public_ip_id": "", "public_ip": "", "nat_gateway_id": "", "nat_public_ip": "" } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Attach a node to a VPC url: https://ibee.ai/docs/api-reference/vpcs/attach-vpc-node last_updated: 2026-10-25 --- # Attach a node to a VPC POST https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nodes Content-Type: application/json Attaches a VM to a VPC subnet so it can reach other VMs on the private network, optionally with a reserved public IP. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl -X POST "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nodes?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"vm_id": "", "subnet_id": ""}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/attach-vpc-node ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an AttachVpcNodeRequest. - `vm_id` (string, required) — ID of the VM to attach. - `subnet_id` (string, required) — Subnet of the VPC to attach the VM to. - `connectivity` (enum, optional, default: private) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. Default `private`. - Allowed values: `private`, `public_ip`, `nat` - `reserved_public_ip_id` (string, optional, nullable) — Reserved IP to attach to the VM. Only valid with `public_ip` connectivity. ## Response ### 201 Node attached successfully. - `allocation_id` (string, required) — Unique ID of the attachment. - `vpc_id` (string, required) — VPC the VM is attached to. - `subnet_id` (string, required) — Subnet the VM is attached to. - `vm_id` (string, required) — ID of the attached VM. - `connectivity` (enum, required) — How the VM reaches the internet from this subnet. - `private`: no internet path. - `public_ip`: a Reserved IP is attached to the allocation. - `nat`: outbound traffic goes through the VPC's NAT gateway. - Allowed values: `private`, `public_ip`, `nat` - `private_ip` (string, required) — Private IPv4 address assigned to the VM. - `prefix_length` (integer, required) — Prefix length of the subnet. - `subnet_mask` (string, required) — Subnet mask in dotted-decimal form. - `gateway` (string, required) — Gateway IPv4 address of the subnet. - `dns` (list of string, required) — DNS resolvers handed to the VM. - `status` (string, required) — Attachment state: `reserved`, `attaching`, `attached`, `moving`, `detaching` or `releasing`. - `public_ip_id` (string, optional, nullable) — Reserved IP attached to the allocation, when `connectivity` is `public_ip`. - `public_ip` (string, optional, nullable) — Address of that Reserved IP. - `nat_gateway_id` (string, optional, nullable) — NAT gateway used, when `connectivity` is `nat`. - `nat_public_ip` (string, optional, nullable) — Public address of that NAT gateway. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "vm_id": "", "subnet_id": "" } ``` **Response** ```json { "allocation_id": "", "vpc_id": "", "subnet_id": "", "vm_id": "", "connectivity": "private", "private_ip": "", "prefix_length": 1, "subnet_mask": "", "gateway": "", "dns": [ "" ], "status": "", "public_ip_id": "", "public_ip": "", "nat_gateway_id": "", "nat_public_ip": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes" querystring = {"workspace_id":"710995"} payload = { "vm_id": "", "subnet_id": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"vm_id":"","subnet_id":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995" payload := strings.NewReader("{\n \"vm_id\": \"\",\n \"subnet_id\": \"\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"vm_id\": \"\",\n \"subnet_id\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"vm_id\": \"\",\n \"subnet_id\": \"\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995', [ 'body' => '{ "vm_id": "", "subnet_id": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"vm_id\": \"\",\n \"subnet_id\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "vm_id": "", "subnet_id": "" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Detach a node from a VPC url: https://ibee.ai/docs/api-reference/vpcs/detach-vpc-node last_updated: 2026-10-25 --- # Detach a node from a VPC DELETE https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nodes/{vm_id} Detaches a VM from a VPC. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # VM_ID: Virtual machine ID curl -X DELETE "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nodes/$VM_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/detach-vpc-node ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `vm_id` (string, required) — Virtual machine ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 204 Node detached successfully. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nodes/vm_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List NAT gateways url: https://ibee.ai/docs/api-reference/vpcs/list-nat-gateways last_updated: 2026-10-25 --- # List NAT gateways GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways Lists the managed NAT gateways in a VPC. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-nat-gateways ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 NAT gateways returned successfully. - `list of NatGateway` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatGateway A managed NAT gateway that gives a VPC's VMs outbound internet access through one public address. - `nat_gateway_id` (string, required) — Unique ID of the gateway. - `vpc_id` (string, required) — VPC the gateway serves. - `site_id` (string, required) — Site the gateway lives at. - `name` (string, required) — Display name of the gateway. - `public_ip_id` (string, required) — ID of the public IP the gateway uses. - `public_ip` (string, required) — Public IPv4 address of the gateway. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ## Examples **Response** ```json [ { "nat_gateway_id": "", "vpc_id": "", "site_id": "", "name": "", "public_ip_id": "", "public_ip": "", "status": "provisioning", "subnet_id": "", "organization_id": "", "workspace_id": "", "pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "error_message": "" } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create a NAT gateway url: https://ibee.ai/docs/api-reference/vpcs/create-nat-gateway last_updated: 2026-10-25 --- # Create a NAT gateway POST https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways Content-Type: application/json Creates a managed NAT gateway that gives VMs in a VPC outbound internet access without public IPs of their own. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID curl -X POST "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"subnet_id": "", "reserved_public_ip_id": ""}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/create-nat-gateway ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateNatGatewayRequest. - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in; chosen by the service when omitted. - `reserved_public_ip_id` (string, optional, nullable) — Reserved IP to use as the gateway's public address; a platform-assigned address is used when omitted. - `name` (string, optional, default: NAT Gateway) — Display name of the gateway. Default `NAT Gateway`. ## Response ### 201 NAT gateway created successfully. - `nat_gateway_id` (string, required) — Unique ID of the gateway. - `vpc_id` (string, required) — VPC the gateway serves. - `site_id` (string, required) — Site the gateway lives at. - `name` (string, required) — Display name of the gateway. - `public_ip_id` (string, required) — ID of the public IP the gateway uses. - `public_ip` (string, required) — Public IPv4 address of the gateway. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `subnet_id` (string, optional, nullable) — Subnet the gateway is placed in. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `pricing` (NatPricing, optional) — Price of a NAT gateway as recorded when it was created. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 402 Payment Required Error Billing refused the request (`billing_denied`). `billing_reason` carries Billing's reason unchanged, for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` (a plan limit) or `resource_usage_unavailable` (Billing could not count usage). `billing_sku_code`, `billing_evaluated_at` and `admission_context_id` identify the decision. Nothing is provisioned; resolve the reason and retry with the same idempotency key where supported. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatPricing Price of a NAT gateway as recorded when it was created. - `currency` (string, optional, default: USD) — ISO 4217 code of the currency the prices are in. - `price_per_hour` (double, optional, default: 0) — Hourly charge for the gateway. - `data_price_per_gb` (double, optional, default: 0) — Charge per GB of data processed. - `billing_enforced` (boolean, optional, default: false) — Whether these charges are being applied. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "subnet_id": "", "reserved_public_ip_id": "" } ``` **Response** ```json { "nat_gateway_id": "", "vpc_id": "", "site_id": "", "name": "", "public_ip_id": "", "public_ip": "", "status": "provisioning", "subnet_id": "", "organization_id": "", "workspace_id": "", "pricing": { "currency": "USD", "price_per_hour": 0, "data_price_per_gb": 0, "billing_enforced": false }, "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways" querystring = {"workspace_id":"710995"} payload = { "subnet_id": "", "reserved_public_ip_id": "" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"subnet_id":"","reserved_public_ip_id":""}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995" payload := strings.NewReader("{\n \"subnet_id\": \"\",\n \"reserved_public_ip_id\": \"\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"subnet_id\": \"\",\n \"reserved_public_ip_id\": \"\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"subnet_id\": \"\",\n \"reserved_public_ip_id\": \"\"\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995', [ 'body' => '{ "subnet_id": "", "reserved_public_ip_id": "" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"subnet_id\": \"\",\n \"reserved_public_ip_id\": \"\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "subnet_id": "", "reserved_public_ip_id": "" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete a NAT gateway url: https://ibee.ai/docs/api-reference/vpcs/delete-nat-gateway last_updated: 2026-10-25 --- # Delete a NAT gateway DELETE https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id} Deletes a NAT gateway from a VPC. VMs that relied on it lose outbound internet access. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # NAT_GATEWAY_ID: NAT gateway ID curl -X DELETE "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways/$NAT_GATEWAY_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/delete-nat-gateway ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `nat_gateway_id` (string, required) — NAT gateway ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 204 NAT gateway deleted successfully. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List NAT port-forwarding rules url: https://ibee.ai/docs/api-reference/vpcs/list-nat-port-forwarding-rules last_updated: 2026-10-25 --- # List NAT port-forwarding rules GET https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules Lists the port-forwarding rules on a NAT gateway. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # NAT_GATEWAY_ID: NAT gateway ID curl "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways/$NAT_GATEWAY_ID/port-forwarding-rules?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/list-nat-port-forwarding-rules ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `nat_gateway_id` (string, required) — NAT gateway ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 200 Port-forwarding rules returned successfully. - `list of NatPortForwardingRule` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### NatPortForwardingRule A port-forwarding rule on a NAT gateway. - `name` (string, required) — Display name of the rule. - `external_port` (integer, required) — Port on the gateway's public address (1-65535). - `internal_ip` (string, required) — Private IPv4 address of the VM inside the VPC that receives the traffic. - `internal_port` (integer, required) — Port on the VM that receives the traffic (1-65535). - `port_forward_rule_id` (string, required) — Unique ID of the rule. - `vpc_id` (string, required) — VPC the rule belongs to. - `nat_gateway_id` (string, required) — NAT gateway the rule is configured on. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the rule was created (ISO 8601). - `updated_at` (datetime, required) — When the rule was last changed (ISO 8601). - `protocol` (enum, optional, default: tcp) — - `tcp` (default) - `udp` - Allowed values: `tcp`, `udp` - `note` (string, optional, default: ) — Free-text note stored with the rule. Default empty. - `enabled` (boolean, optional, default: true) — Whether the rule is applied. Default true. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `site_id` (string, optional) — Site the gateway lives at. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json [ { "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1, "port_forward_rule_id": "", "vpc_id": "", "nat_gateway_id": "", "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "protocol": "tcp", "note": "", "enabled": true, "organization_id": "", "workspace_id": "", "site_id": "", "error_message": "" } ] ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Create a NAT port-forwarding rule url: https://ibee.ai/docs/api-reference/vpcs/create-nat-port-forwarding-rule last_updated: 2026-10-25 --- # Create a NAT port-forwarding rule POST https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules Content-Type: application/json Adds a port-forwarding rule that sends traffic arriving on a NAT gateway port to a private IP and port inside the VPC. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # NAT_GATEWAY_ID: NAT gateway ID curl -X POST "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways/$NAT_GATEWAY_ID/port-forwarding-rules?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "", "external_port": 1, "internal_ip": "", "internal_port": 1}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/create-nat-port-forwarding-rule ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `nat_gateway_id` (string, required) — NAT gateway ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects a CreateNatPortForwardingRuleRequest. - `name` (string, required) — Display name of the rule. - `external_port` (integer, required) — Port on the gateway's public address (1-65535). - `internal_ip` (string, required) — Private IPv4 address of the VM inside the VPC that receives the traffic. - `internal_port` (integer, required) — Port on the VM that receives the traffic (1-65535). - `protocol` (enum, optional, default: tcp) — - `tcp` (default) - `udp` - Allowed values: `tcp`, `udp` - `note` (string, optional, default: ) — Free-text note stored with the rule. Default empty. - `enabled` (boolean, optional, default: true) — Whether the rule is applied. Default true. ## Response ### 201 Port-forwarding rule created successfully. - `name` (string, required) — Display name of the rule. - `external_port` (integer, required) — Port on the gateway's public address (1-65535). - `internal_ip` (string, required) — Private IPv4 address of the VM inside the VPC that receives the traffic. - `internal_port` (integer, required) — Port on the VM that receives the traffic (1-65535). - `port_forward_rule_id` (string, required) — Unique ID of the rule. - `vpc_id` (string, required) — VPC the rule belongs to. - `nat_gateway_id` (string, required) — NAT gateway the rule is configured on. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the rule was created (ISO 8601). - `updated_at` (datetime, required) — When the rule was last changed (ISO 8601). - `protocol` (enum, optional, default: tcp) — - `tcp` (default) - `udp` - Allowed values: `tcp`, `udp` - `note` (string, optional, default: ) — Free-text note stored with the rule. Default empty. - `enabled` (boolean, optional, default: true) — Whether the rule is applied. Default true. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `site_id` (string, optional) — Site the gateway lives at. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1 } ``` **Response** ```json { "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1, "port_forward_rule_id": "", "vpc_id": "", "nat_gateway_id": "", "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "protocol": "tcp", "note": "", "enabled": true, "organization_id": "", "workspace_id": "", "site_id": "", "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules" querystring = {"workspace_id":"710995"} payload = { "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1 } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"","external_port":1,"internal_ip":"","internal_port":1}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\",\n \"external_port\": 1,\n \"internal_ip\": \"\",\n \"internal_port\": 1\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\",\n \"external_port\": 1,\n \"internal_ip\": \"\",\n \"internal_port\": 1\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\",\n \"external_port\": 1,\n \"internal_ip\": \"\",\n \"internal_port\": 1\n}") .asString(); ``` ```php request('POST', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995', [ 'body' => '{ "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1 }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\",\n \"external_port\": 1,\n \"internal_ip\": \"\",\n \"internal_port\": 1\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Delete a NAT port-forwarding rule url: https://ibee.ai/docs/api-reference/vpcs/delete-nat-port-forwarding-rule last_updated: 2026-10-25 --- # Delete a NAT port-forwarding rule DELETE https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules/{port_forwarding_rule_id} Removes a port-forwarding rule from a NAT gateway. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # NAT_GATEWAY_ID: NAT gateway ID # PORT_FORWARDING_RULE_ID: NAT port-forwarding rule ID curl -X DELETE "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways/$NAT_GATEWAY_ID/port-forwarding-rules/$PORT_FORWARDING_RULE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/vpcs/delete-nat-port-forwarding-rule ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `nat_gateway_id` (string, required) — NAT gateway ID. - `port_forwarding_rule_id` (string, required) — NAT port-forwarding rule ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ## Response ### 204 Port-forwarding rule deleted successfully. ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123" querystring = {"workspace_id":"710995"} headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995") .header("Authorization", "Bearer ") .asString(); ``` ```php request('DELETE', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: Update a NAT port-forwarding rule url: https://ibee.ai/docs/api-reference/vpcs/update-nat-port-forwarding-rule last_updated: 2026-10-25 --- # Update a NAT port-forwarding rule PATCH https://api.ibee.ai/v1/networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rules/{port_forwarding_rule_id} Content-Type: application/json Changes a NAT port-forwarding rule's ports, target, protocol, or enabled state. Requires scope: network.write. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). # VPC_ID: VPC ID # NAT_GATEWAY_ID: NAT gateway ID # PORT_FORWARDING_RULE_ID: NAT port-forwarding rule ID curl -X PATCH "https://api.ibee.ai/v1/networking/vpcs/$VPC_ID/nat-gateways/$NAT_GATEWAY_ID/port-forwarding-rules/$PORT_FORWARDING_RULE_ID?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "", "protocol": "tcp"}' ``` Reference: https://ibee.ai/docs/api-reference/vpcs/update-nat-port-forwarding-rule ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Path parameters - `vpc_id` (string, required) — VPC ID. - `nat_gateway_id` (string, required) — NAT gateway ID. - `port_forwarding_rule_id` (string, required) — NAT port-forwarding rule ID. ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. ### Body (application/json) This endpoint expects an UpdateNatPortForwardingRuleRequest. - `name` (string, optional) — Display name of the rule. - `protocol` (enum, optional) — - `tcp` - `udp` - Allowed values: `tcp`, `udp` - `external_port` (integer, optional) — Port on the gateway's public address (1-65535). - `internal_ip` (string, optional) — Private IPv4 address of the VM inside the VPC that receives the traffic. - `internal_port` (integer, optional) — Port on the VM that receives the traffic (1-65535). - `note` (string, optional) — Free-text note stored with the rule. - `enabled` (boolean, optional) — Whether the rule is applied. ## Response ### 200 Port-forwarding rule updated successfully. - `name` (string, required) — Display name of the rule. - `external_port` (integer, required) — Port on the gateway's public address (1-65535). - `internal_ip` (string, required) — Private IPv4 address of the VM inside the VPC that receives the traffic. - `internal_port` (integer, required) — Port on the VM that receives the traffic (1-65535). - `port_forward_rule_id` (string, required) — Unique ID of the rule. - `vpc_id` (string, required) — VPC the rule belongs to. - `nat_gateway_id` (string, required) — NAT gateway the rule is configured on. - `status` (enum, required) — Lifecycle status of a VPC, subnet, NAT gateway or port-forwarding rule. - `provisioning`: being created. - `available`: ready for use. - `error`: the last change failed; see `error_message`. - `deleting`: being removed. - Allowed values: `provisioning`, `available`, `error`, `deleting` - `created_at` (datetime, required) — When the rule was created (ISO 8601). - `updated_at` (datetime, required) — When the rule was last changed (ISO 8601). - `protocol` (enum, optional, default: tcp) — - `tcp` (default) - `udp` - Allowed values: `tcp`, `udp` - `note` (string, optional, default: ) — Free-text note stored with the rule. Default empty. - `enabled` (boolean, optional, default: true) — Whether the rule is applied. Default true. - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `site_id` (string, optional) — Site the gateway lives at. - `error_message` (string, optional, nullable) — Error detail when `status` is `error`. ## Errors ### 400 Bad Request Error The request is invalid. From the gateway: `workspace_id_required` or `invalid_workspace_id`; on billable creates also `invalid_json_body` and selection codes such as `plan_id_required`, `invalid_site_id`, `compute_billing_term_required` or `invalid_block_storage_selection`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 404 Not Found Error The requested resource was not found. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 409 Conflict Error The request conflicts with the current resource state. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 423 Locked Error The organization is suspended (`organization_suspended`), so writes are refused. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Request** ```json { "name": "", "protocol": "tcp" } ``` **Response** ```json { "name": "", "external_port": 1, "internal_ip": "", "internal_port": 1, "port_forward_rule_id": "", "vpc_id": "", "nat_gateway_id": "", "status": "provisioning", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "protocol": "tcp", "note": "", "enabled": true, "organization_id": "", "workspace_id": "", "site_id": "", "error_message": "" } ``` **SDK Code** ```python import requests url = "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123" querystring = {"workspace_id":"710995"} payload = { "name": "", "protocol": "tcp" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"name":"","protocol":"tcp"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995" payload := strings.NewReader("{\n \"name\": \"\",\n \"protocol\": \"tcp\"\n}") req, _ := http.NewRequest("PATCH", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Patch.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"\",\n \"protocol\": \"tcp\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.patch("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"\",\n \"protocol\": \"tcp\"\n}") .asString(); ``` ```php request('PATCH', 'https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995', [ 'body' => '{ "name": "", "protocol": "tcp" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995"); var request = new RestRequest(Method.PATCH); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"\",\n \"protocol\": \"tcp\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "name": "", "protocol": "tcp" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ibee.ai/v1/networking/vpcs/vpc_123/nat-gateways/nat_gateway_123/port-forwarding-rules/port_forwarding_rule_123?workspace_id=710995")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PATCH" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` --- title: List Reserved IPs url: https://ibee.ai/docs/api-reference/reserved-ips/list-reserved-ips last_updated: 2026-10-25 --- # List Reserved IPs GET https://api.ibee.ai/v1/networking/reserved-ips Lists customer-reserved public IP addresses. Requires scope: network.read. ``` # Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first). curl "https://api.ibee.ai/v1/networking/reserved-ips?workspace_id=$WORKSPACE_ID" \ -H "Authorization: Bearer $IBEE_API_TOKEN" ``` Reference: https://ibee.ai/docs/api-reference/reserved-ips/list-reserved-ips ## Authentication - `Authorization` header (bearer token, required) — IBEE platform API token. Production tokens start with `ibee_prod_key_`; development tokens start with `ibee_dev_key_`. Use a token only with its matching gateway environment. ## Servers - `https://api.ibee.ai/v1` (Production, default) - `https://api.ibee.co.in/v1` (Development) ## Request ### Query parameters - `workspace_id` (string, required) — The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected. - `site_id` (string, optional) — Optional exact site filter. Copy `site_id` from `GET /networking/sites`. ## Response ### 200 Reserved IPs returned successfully. - `list of ReservedIp` ## Errors ### 401 Unauthorized Error The API token is missing, malformed or unknown (`invalid_api_key`). - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 403 Forbidden Error The token may not make this call. Gateway codes: `insufficient_scope` (with `required_scope`), `key_revoked`, `key_disabled`, `key_inactive`, `key_expired`, `unknown_route`, `workspace_not_allowed`, `principal_inactive`, `principal_not_member` and `principal_permission_denied`. On writes, also `organization_restricted` (an admin restricted the organization) and `verification_required` (the token's user has not completed identity verification). A product service may also refuse with `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ### 503 Service Unavailable Error A service the request depends on did not answer. Gateway codes: `workspace_verification_unavailable`, `principal_verification_unavailable` and `principal_authorization_unavailable`; on billable creates also `billing_admission_timeout`, `billing_admission_unavailable`, `billing_admission_disabled`, `billing_admission_not_configured` and the catalog codes `compute_catalog_unavailable`, `compute_catalog_not_configured`, `product_catalog_timeout`, `product_catalog_unavailable`, `product_catalog_not_configured` and `unsupported_product_quote`. Otherwise the product service's `detail`. - `error` (string, optional, nullable) — Machine-readable code from the gateway's authorization step, for example `invalid_api_key`, `insufficient_scope`, `organization_restricted`, `organization_suspended`, `verification_required` or `billing_denied`. The response descriptions list the codes for each status. - `required_scope` (string, optional, nullable) — The scope the token lacks, with `insufficient_scope`. - `billing_reason` (string, optional, nullable) — Billing's reason with `billing_denied`, passed through unchanged: for example `insufficient_balance`, `credit_limit_exceeded`, `initial_topup_required`, `resource_limit_reached` or `resource_usage_unavailable`. - `billing_sku_code` (string, optional, nullable) — The SKU the billing admission checked, when there was one. - `billing_evaluated_at` (string, optional, nullable) — When Billing made the decision, as Billing returned it. - `admission_context_id` (string, optional, nullable) — Billing admission context for this request, derived from the token, workspace, route and `X-Idempotency-Key`, so a retry with the same key gets the same id. - `detail` (ErrorDetail, optional) — Error detail from the product service. ## Types ### ReservedIp A portable public IPv4 address reserved by the workspace. It stays allocated until released and can be moved between VMs. - `public_ip_id` (string, required) — Unique ID of the Reserved IP. - `address` (string, required) — The IPv4 address. - `site_id` (string, required) — Site whose pool the address comes from. - `status` (string, required) — `reserved` when not attached, `attached` when in use, `releasing` while being released. - `created_at` (datetime, required) — When the resource was created (ISO 8601). - `updated_at` (datetime, required) — When the resource was last changed (ISO 8601). - `organization_id` (string, optional) — ID of the owning organization. - `workspace_id` (string, optional) — ID of the owning workspace. - `label` (string, optional) — Label shown as the address's name in the portal. - `reverse_dns` (string, optional) — Reverse DNS hostname set on the address; empty when none. - `reservation_type` (enum, optional, nullable) — - `user_reserved`: a Reserved IP created by the customer. - `platform_assigned`: an address IBEE assigned to an instance or service. Null on legacy records whose classification the service infers. - Allowed values: `user_reserved`, `platform_assigned` - `attached_resource_type` (string, optional, nullable) — Kind of resource the address is attached to, for example `vm` or `nat_gateway`; null when not attached. - `attached_resource_id` (string, optional, nullable) — ID of that resource; null when not attached. - `attached_vpc_id` (string, optional, nullable) — VPC of the attachment, when the address is attached inside a VPC. - `attached_subnet_id` (string, optional, nullable) — Subnet of the attachment, when the address is attached inside a VPC. ### ErrorDetail Error detail from the product service. - string - map from string to any - list of any ## Examples **Response** ```json [ { "public_ip_id": "", "address": "
", "site_id": "", "status": "", "created_at": "2026-10-25T12:00:00Z", "updated_at": "2026-10-25T12:00:00Z", "organization_id": "", "workspace_id": "", "label": "