Skip to main content

Get started with MAG

note

Your project must be approved for MAG before you can use MAG.

This video shows how to access MAG and generate a PAT. The steps below give the details.

1. Request an Account​

  1. See Access and Login for details.

2. Request access to an AmSC project​

  • If you are a project PI and your account is approved, follow the steps listed under Request an AmSC project.
  • If you are a project member, and you account is approved, follow the steps listed under Joining a project.
note

The project must request a MAG allocation to use MAG.

3. Create a MAG PAT (Personal Access Token)​

The PAT is an API key. You send it to MAG as the bearer token. It is short-lived. When it expires, MAG returns 401 Unauthorized. Generate a new PAT on myAmSC.

warning

MyAmSC shows the complete PAT only once. Copy the PAT before you close the window. If you lose it, generate a new PAT.

A PAT gives access to your account. Store it in an environment variable. Do not put it in source code. Do not share it. Do not commit it to a Git repository.

See Best Practices for PAT Safety.

  1. Wait until your project membership request is approved.
  2. Log in to the myAmSC dashboard.
  3. In the left navigation, select your AmSC Genesis Mission RFA project.
  4. Select Personal Access Tokens, then select Generate PAT.
  5. Enter a description in the Token Description field. Select Submit.
  6. If prompted, authorize Ping Identity (the AmSC IdP) to access your profile.
  7. Copy the PAT that myAmSC shows.

4. Setup PAT in your client​

AMSC_TOKEN is the name of an environment variable. It is not the PAT. The PAT is the secret value that you store in this variable.

Add the variable to your shell startup file, so that every new terminal has it.

  1. Open the startup file of your shell. Use ~/.zshrc for zsh (the macOS default). Use ~/.bashrc for bash.

  2. Add this line. Replace <key> with the PAT that you copied:

    export AMSC_TOKEN=<key>

  3. Save the file.

  4. Open a new terminal. Or run source ~/.zshrc (or source ~/.bashrc) in the current terminal.

On Windows, set a user environment variable. See about_Environment_Variables for the steps.

If the variable is not active in an application, log out and log in again. Then start the application again.

Other examples in this guide use $AMSC_TOKEN to read the PAT from the variable. Do not write the PAT in a command or in the code of an application.

You can confirm that the variable exists without displaying the key:

if [ -n "$AMSC_TOKEN" ]; then echo "MAG PAT is set"; else echo "MAG PAT is not set"; fi

You should see:

MAG PAT is set

You can also check that the value has the format of a PAT. This check does not show the key and does not confirm that the PAT has not expired:

echo "${AMSC_TOKEN#*.}" | cut -d. -f1 | tr '_-' '/+' | base64 -d >/dev/null 2>&1 && echo "Token Encoding Valid" || echo "Token Invalid"

You should see:

Token Encoding Valid

5. Verify your access and list models​

Run:

curl --request GET \
  --url https://mag.genesis.americansciencecloud.org/v1/models \
  --header "Authorization: Bearer $AMSC_TOKEN" | jq

A successful response contains model information in JSON format. If you receive an authentication error, see Troubleshooting. If the request is blocked by an IP restriction, your client may be connecting over IPv6; see Requests are blocked by an IP restriction.

The live response is the best way to determine which models are currently available to your account. Syntax and interactive examples for other API calls are available at https://mag.genesis.americansciencecloud.org.

6. Send your first request​

Use a chat model to send a message. This example uses gpt-6-luna, a low-cost model. The header X-AmSC-MAG-Provider selects the provider that serves the model:

curl --request POST \
  --url https://mag.genesis.americansciencecloud.org/v1/chat/completions \
  --header "Authorization: Bearer $AMSC_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-AmSC-MAG-Provider: openai" \
  --data '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "In one sentence, explain what an AI model is."}
    ]
  }' | jq

To use Microsoft Azure instead, change the header to X-AmSC-MAG-Provider: microsoft.

A successful JSON response includes the model's reply under choices → message → content. You are now ready to use MAG directly or connect it to an OpenAI-compatible application.