Add documentation for the universal sign up page and PATs

docs/source/getting_started/getting_started.ipynb

@@ -29,17 +29,21 @@
    "source": [
     "### Signing up for a new MAAP account\n",
     "\n",
-    "Once registered, you can register for a MAAP account by navigating to the MAAP Hub at https://hub.maap-project.org/. On your first visit, select the \"Login with EarthData Account\" button shown here:\n",
+    "MAAP uses your Earthdata Login account to sign in — there is no separate MAAP registration form. Signing in for the first time creates your MAAP account automatically.\n",
+    "\n",
+    "1. Navigate to the MAAP Signup page at https://maap-project.org/signup.\n",
+    "2. Select the **Get started with Earthdata Login** button and enter your Earthdata Login credentials.\n",
     "\n",
     "![Hub Login](_static/hub_login.png)  \n",
     "\n",
-    "Once registered, you will be redirect to this page \n",
+    "3. On your first sign-in, a MAAP account is created for you and placed in a *pending* state. You will be taken to a sign-up page confirming that your request has been received and is awaiting review:\n",
+    "\n",
     "![Requested Account](_static/requested_account.png)  \n",
     "  \n",
-    "At this point, a MAAP administrator will approve your account, which will grant you access to the MAAP Hub. **Remember, access is only granted to known users in the biomass science community and other projects directly related to MAAP**. To check on the status of your pending account, contact the MAAP team at support@maap-project.org.\n",
+    "A MAAP administrator will then review your request. **Access is only granted to users in NASA-Affiliated research, ESA Biomass users and other projects directly related to MAAP.** Until your account is approved, signing in to the Hub will return you to this pending page.\n",
     "\n",
     ".. note::\n",
-    "    Once your MAAP account is approved, you will receive an email notification using the address of your Earthdata Login account to let you know that your access is enabled."
+    "    Once your MAAP account is approved, you will receive an email notification at the address associated with your Earthdata Login account to let you know that your access is enabled. To check on the status of a pending account, contact the MAAP team at support@maap-project.org."
    ]
   },
   {
@@ -49,15 +53,18 @@
    "source": [
     "### Logging in\n",
     "\n",
-    "1. Navigate to https://hub.maap-project.org/ in Chrome or Firefox. You should be redirected to a page that looks like this:\n",
+    "1. Navigate to https://hub.maap-project.org/ in Chrome or Firefox. You should be redirected to a sign-in page:\n",
     "![Hub Login](_static/hub_login.png)\n",
     "\n",
-    "2. Click the \"Sign in with EarthData Login” button. If this is your first time logging in, you should be redirected to an EarthData Login page that looks like this:\n",
+    "2. Click the **Sign in with Earthdata Login** button. You will be redirected to Earthdata Login to enter your credentials:\n",
     "![Login with EarthData](_static/loggingin2.png)\n",
     "\n",
     "\n",
-    "3. Enter your “EarthData Login” account credentials here and click “Log in”. You should see a temporary page that says “Redirecting”, followed by the MAAP Hub launch page:\n",
-    "![MAAP Jupyter logging in](_static/hub_launch_page.png)"
+    "3. Enter your Earthdata Login credentials and click “Log in”. After a brief page that says “Redirecting”, you will arrive at the MAAP Hub launch page:\n",
+    "![MAAP Jupyter logging in](_static/hub_launch_page.png)\n",
+    "\n",
+    ".. note::\n",
+    "    If your MAAP account has not been approved yet, signing in will take you to the pending sign-up page described in \"Signing up for a new MAAP account\" above, rather than the Hub launch page."
    ]
   },
   {

docs/source/system_reference.rst

@@ -19,6 +19,7 @@ It is often referenced from the application-focused Science and Technical tutori
   system_reference_guide/dps_queues.ipynb
   system_reference_guide/work_with_git.ipynb
   system_reference_guide/organizations.ipynb
+  system_reference_guide/personal_access_tokens.rst
   system_reference_guide/ssh.ipynb
   system_reference_guide/accessing_bucket_data.ipynb
   system_reference_guide/ade_custom_extensions.rst

docs/source/system_reference_guide/organizations.ipynb

@@ -12,65 +12,7 @@
    "cell_type": "markdown",
    "id": "cd3c4962",
    "metadata": {},
-   "source": [
-    "## Organization Membership within MAAP\n",
-    "\n",
-    "MAAP Organizations were added in version 4.1.0 to control access to job queues and other MAAP resources. Users may be assigned to one or more organizations within the MAAP hierarchy of organization teams. Users within these teams may be designated as Org Maintainers. \n",
-    "\n",
-    "In a future version of MAAP, Org Maintainers will have the ability to add and remove members to their teams, as well assign job queue resource limits per user as needed. As of version 4.1.0, organization membership is controlled strictly by MAAP administrators.\n",
-    "\n",
-    "## Job Queue Access\n",
-    "\n",
-    "Only job queues assigned to your organization(s) will be allowed for use when registering an algorithm or submitting jobs. When submitting jobs via the Jobs UI, only your org-assigned queues are visible in the queue selection menu. Any publicly-accessible queues, such as the sandbox queue, are accessible to all users of the MAAP platform.\n",
-    "\n",
-    "See the [Queues page](dps_queues.ipynb) for more information about the current queues.\n",
-    "\n",
-    "### Viewing Your Organizations\n",
-    "\n",
-    "```\n",
-    "from maap.maap import MAAP\n",
-    "import json\n",
-    "maap = MAAP()\n",
-    "\n",
-    "me = maap.profile.account_info()\n",
-    "print(json.dumps(me, indent=2))\n",
-    ">>> {\n",
-    "  \"id\": 1,\n",
-    "  \"username\": \"maap_user\",\n",
-    "  \"email\": \"maap_user@nasa.gov\",\n",
-    "  \"first_name\": \"MAAP\",\n",
-    "  \"last_name\": \"User\",\n",
-    "  \"status\": \"active\",\n",
-    "  \"creation_date\": \"2023-06-14T21:09:57.922240\",\n",
-    "  \"organizations\": [\n",
-    "    {\n",
-    "      \"id\": 1,\n",
-    "      \"name\": \"Dev Team\"\n",
-    "    }\n",
-    "  ]\n",
-    "}\n",
-    "```\n",
-    "\n",
-    "### Viewing Your Job Queues\n",
-    "\n",
-    "```\n",
-    "from maap.maap import MAAP\n",
-    "import json\n",
-    "maap = MAAP()\n",
-    "\n",
-    "me = maap.getQueues().json()\n",
-    "print(json.dumps(me, indent=2))\n",
-    ">>> {\n",
-    "  \"code\": 200,\n",
-    "  \"message\": \"success\",\n",
-    "  \"queues\": [\n",
-    "    \"maap-dps-worker-16gb\",\n",
-    "    \"maap-dps-worker-8gb\",\n",
-    "    \"maap-dps-sandbox\"\n",
-    "  ]\n",
-    "}\n",
-    "```"
-   ]
+   "source": "## Organization Membership within MAAP\n\nMAAP Organizations control access to job queues and other MAAP resources. Users may be assigned to one or more organizations within the MAAP hierarchy of organization teams. Users within these teams may be designated as **Org Maintainers**.\n\nOrg Maintainers can manage their own team's membership directly from the MAAP Console — adding and removing members and setting per-member job limits — without needing to go through a MAAP administrator. Members who are not maintainers have read-only visibility into the organizations they belong to.\n\n### Managing your organization's members (Org Maintainers)\n\nIf you are an Org Maintainer, you can manage your team from the MAAP Console:\n\n1. Sign in to the MAAP Console at https://console.maap-project.org and open **Profile → Organizations**.\n2. Each organization you belong to shows your role (**Maintainer** or **Member**) and the organization's default job limit. Expand an organization where you are a Maintainer to open its management panel.\n3. From the panel you can:\n   - **Add a member** — type a username into the **Add members...** box and select the user. New members are added as regular members.\n   - **Set a per-member job limit** — override the organization's default job limit (count and/or hours) for an individual member. Leave a field blank to use the organization's default.\n   - **Remove a member** — remove a user from the organization.\n\n![Organization management panel for Org Maintainers](../_static/organizations/org_manage_panel.png)\n\nA member's *effective* job limit is their per-member override when one is set, otherwise the organization's default.\n\n.. note::\n    You cannot remove yourself from an organization you maintain, since that would revoke the maintainer rights the change depends on. Ask another maintainer or a MAAP administrator if you need to be removed. Creating organizations, designating maintainers, and assigning job queues to an organization remain MAAP administrator functions.\n\n## Job Queue Access\n\nOnly job queues assigned to your organization(s) will be allowed for use when registering an algorithm or submitting jobs. When submitting jobs via the Jobs UI, only your org-assigned queues are visible in the queue selection menu. Any publicly-accessible queues, such as the sandbox queue, are accessible to all users of the MAAP platform.\n\nSee the [Queues page](dps_queues.ipynb) for more information about the current queues.\n\n### Viewing Your Organizations\n\n```\nfrom maap.maap import MAAP\nimport json\nmaap = MAAP()\n\nme = maap.profile.account_info()\nprint(json.dumps(me, indent=2))\n>>> {\n  \"id\": 1,\n  \"username\": \"maap_user\",\n  \"email\": \"maap_user@nasa.gov\",\n  \"first_name\": \"MAAP\",\n  \"last_name\": \"User\",\n  \"status\": \"active\",\n  \"creation_date\": \"2023-06-14T21:09:57.922240\",\n  \"organizations\": [\n    {\n      \"id\": 1,\n      \"name\": \"Dev Team\"\n    }\n  ]\n}\n```\n\n### Viewing Your Job Queues\n\n```\nfrom maap.maap import MAAP\nimport json\nmaap = MAAP()\n\nme = maap.getQueues().json()\nprint(json.dumps(me, indent=2))\n>>> {\n  \"code\": 200,\n  \"message\": \"success\",\n  \"queues\": [\n    \"maap-dps-worker-16gb\",\n    \"maap-dps-worker-8gb\",\n    \"maap-dps-sandbox\"\n  ]\n}\n```"
   }
  ],
  "metadata": {
@@ -94,4 +36,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/source/system_reference_guide/personal_access_tokens.rst

@@ -0,0 +1,112 @@
+Personal Access Tokens
+=======================================
+
+Personal Access Tokens (PATs) are long-lived credentials you can use to
+authenticate to the MAAP API from outside the MAAP Hub — for example, when
+running ``maap-py`` on your local machine or from an automated script. A PAT
+takes the place of the short-lived session token that the Hub manages for you
+automatically, so you no longer need to copy a temporary token out of a running
+workspace.
+
+MAAP supports two kinds of tokens:
+
+* **NASA** tokens authenticate to NASA MAAP resources.
+* **ESA** tokens authenticate to ESA MAAP resources and are managed on ESA's
+  gateway on your behalf (see :ref:`pat-nasa-esa`).
+
+.. note::
+   You do **not** need a Personal Access Token inside the MAAP Hub. Workspaces
+   are authenticated automatically. PATs are only for programmatic access from
+   outside the Hub.
+
+Creating a token
+----------------
+
+The **Personal Access Tokens** tab in the MAAP Console lists your existing
+tokens and is where you create new ones:
+
+.. image:: ../_static/personal_access_tokens/pat_list.png
+   :alt: The Personal Access Tokens tab in the MAAP Console
+   :width: 100%
+
+To create a token:
+
+1. Sign in to the MAAP Console at https://console.maap-project.org.
+2. Open the **Profile** area and select the **Personal Access Tokens** tab.
+3. Click **Create Token** and choose:
+
+   * **Token Name** *(optional)* — a label to help you recognize the token
+     later (for example, ``laptop`` or ``ci-pipeline``).
+   * **Platform** — **NASA** or **ESA**, depending on which resources the token
+     will access.
+   * **Expiration** — ``1 day``, ``7 days``, ``30 days``, ``90 days``, ``1 year``, or ``No expiration``.
+
+4. Click **Create**. The token value is displayed **once** — copy it
+   immediately and store it somewhere safe. You will not be able to view it
+   again.
+
+.. image:: ../_static/personal_access_tokens/pat_create.png
+   :alt: The Create Token dialog with token name, platform, and expiration fields
+   :width: 100%
+
+.. warning::
+   Treat a Personal Access Token like a password. Anyone who has it can act as
+   you against the MAAP API. Store it as an environment variable or in a secrets
+   manager — never commit it to a Git repository or paste it into a shared
+   notebook.
+
+Using a token with maap-py
+--------------------------
+
+Outside the Hub, ``maap-py`` reads your token from the ``MAAP_PGT`` environment
+variable. Set it to your Personal Access Token before initializing ``MAAP``:
+
+.. code-block:: python
+
+   import os
+   os.environ["MAAP_PGT"] = "<your-personal-access-token>"
+
+   from maap.maap import MAAP
+   maap = MAAP()
+
+   # maap-py now authenticates as you
+   me = maap.profile.account_info()
+
+Alternatively, export the variable in your shell before launching Python:
+
+.. code-block:: bash
+
+   export MAAP_PGT="<your-personal-access-token>"
+
+.. _pat-nasa-esa:
+
+NASA and ESA tokens
+-------------------
+
+MAAP is a joint NASA/ESA platform. When you create a token you choose which
+platform it targets:
+
+* A **NASA** token is stored and validated by NASA MAAP.
+* An **ESA** token is created on, and validated by, the ESA MAAP gateway. NASA
+  users can create and manage ESA tokens directly from the NASA MAAP Console —
+  the Console proxies the request to ESA for you. ESA tokens are typically used
+  as a ``Bearer`` token when accessing ESA-hosted data. For worked examples, see
+  the ESA BIOMASS and ESA CCI data-access tutorials in the Science section.
+
+Managing your tokens
+---------------------
+
+The **Personal Access Tokens** tab lists your tokens with their platform
+(NASA/ESA), status, creation date, and expiration:
+
+* **Revoke** — click *Revoke* on a token to invalidate it immediately. Any
+  script still using that token will stop working.
+* **Status** — a token is *Active*, *Expired* (past its expiration), or
+  *Revoked*.
+* **Show expired** — expired tokens are hidden by default. Toggle **Show
+  expired** to display them.
+
+.. note::
+   Tokens are tied to your MAAP membership. If your account is suspended, your
+   tokens will not authenticate until the account is reactivated. Create a new
+   token whenever one expires — expired tokens cannot be renewed.