{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to authenticate using an API key\n",
    "**Authenticate your Boulder Opal session without a browser**"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can seamlessly authenticate to the Q-CTRL platform using API key-based authentication by passing an API key from your Python client environment.\n",
    "\n",
    "In this guide, you will learn how to retrieve an API key and use it to authenticate your session."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Retrieve your API key \n",
    "\n",
    "Sign in to [Q-CTRL Accounts](https://accounts.q-ctrl.com/). Under [Sign in and security](https://accounts.q-ctrl.com/security?organization=), copy the pre-generated API key. You also have the ability to generate additional keys."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Authenticate using your API key\n",
    "\n",
    "In your client environment, you can call `boulderopal.cloud.authenticate` and pass the respective API key to authenticate with the Q-CTRL platform."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import boulderopal as bo\n",
    "\n",
    "bo.cloud.authenticate(api_key=\"YOUR_QCTRL_API_KEY\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Set an environment variable to persist authentication (optional)\n",
    "\n",
    "To avoid re-authenticating, you may choose to simply set the `QCTRL_API_KEY` environment variable to your key's value. Note that if you don't set the environment variable or call `boulderopal.cloud.authenticate` explicitly, you will be redirected to a browser for authentication."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "export QCTRL_API_KEY=\"YOUR_QCTRL_API_KEY\""
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.0"
  },
  "vscode": {
   "interpreter": {
    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}