{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authentication\n",
    "\n",
    "This guide focuses on the basics of authentication in CARTOframes.\n",
    "\n",
    "Authentication is needed to store your data tables and map visualizations in your CARTO account, to use [Data Services](/developers/cartoframes/guides/Data-Services/) (geocoding, isolines) or the [Data Observatory](/developers/cartoframes/guides/Data-Observatory/) (download, enrichment). If you don't already have an account, you can [create one here](https://carto.com/signup/).\n",
    "\n",
    "> You don't need to be authenticated to visualize your local data with CARTOframes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting your API Key\n",
    "Once you have created an account, you need to get your **Master API Key**. The API keys page can be accessed from your [CARTO Dashboard](https://carto.com/help/tutorials/your-dashboard-overview/). Once there, click on your avatar to open the dashboard menu. The API keys link will be shown.\n",
    "\n",
    "![API Keys link - CARTO Dashboard](img/credentials/dashboard.png)\n",
    "\n",
    "From here, copy the **Master** API Key to use in the next section.\n",
    "\n",
    "![Master API Key - CARTO Dashboard](img/credentials/api-keys.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting your credentials\n",
    "\n",
    "[Credentials](/developers/cartoframes/reference/#heading-Auth) class is used to load your credentials in CARTOframes. This should be passed to every method that interacts with your CARTO account. You can create multiple instances of credentials to manage different CARTO accounts.\n",
    "\n",
    "There are different ways to set them but we recommend using the one that reads the credentials from a JSON file:\n",
    "\n",
    "```py\n",
    "from cartoframes.auth import Credentials\n",
    "\n",
    "creds = Credentials.from_file('creds.json')\n",
    "```\n",
    "\n",
    "With [set_default_credentials](/developers/cartoframes/reference/#heading-Auth), the same user's authentication will be used by every CARTOframes component by default, so you don't need to pass the parameter to every method that requires it.\n",
    "\n",
    "```py\n",
    "from cartoframes.auth import set_default_credentials\n",
    "\n",
    "set_default_credentials('creds.json')\n",
    "```\n",
    "\n",
    "Example `creds.json` file using the credentials above:\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"username\": \"johnsmith\",\n",
    "  \"api_key\": \"b1ff3ed88761070116180189d9a1f5cb9cc80654\"\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Credential parameters\n",
    "\n",
    "- `username`: your CARTO account username\n",
    "- `api_key`: your CARTO account API Key. If the data to be accessed is **public**, it can be set to `default_public`\n",
    "- `base_url`: only needed for on-premise or custom installations. Typically in the form of `https://username.carto.com/` for user `username`. On-premises installation (and others) may have a different URL pattern."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Google Cloud credentials\n",
    "\n",
    "CARTO's [Data Observatory](/developers/cartoframes/guides/Data-Observatory/) is built on top of Google BigQuery, so every CARTO Enterprise organization has an associated Google Cloud account to run Data Observatory operations.\n",
    "\n",
    "In case you have an Enterprise account and want to perform data operations directly with the Python BigQuery client, you can obtain the credentials of the associated Google Cloud account and create a Google Credentials instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cartoframes.auth import Credentials\n",
    "from google.oauth2.credentials import Credentials as GoogleCredentials\n",
    "\n",
    "creds = Credentials.from_file('creds.json')\n",
    "\n",
    "gcloud_project, gcloud_token = creds.get_gcloud_credentials()\n",
    "gcloud_credentials = GoogleCredentials(gcloud_token)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}