Quickstart

Get up and running with Satélite API in minutes

Prerequisites

Before you begin, ensure you have:

• A valid Microsoft Azure AD account with @moderna.com.ec email domain
• An HTTP client (Postman, Insomnia, or curl)
• Basic understanding of GraphQL concepts

Only users with email addresses ending in @moderna.com.ec can authenticate with the API.

Step 1: Obtain an Authentication Token

First, you need to authenticate using your Microsoft Azure AD token. The API uses a two-step authentication process:

1. Provide your Azure AD access token
2. Receive a Satélite API JWT token for subsequent requests

Authentication Request

Send a GraphQL mutation to the /graphql endpoint:

mutation {
  authenticate {
    token
    usuario {
      id
      nombre
      email
      activo
    }
    permisos {
      id
      idPermiso
      permiso {
        nombre
      }
    }
    menu {
      id
      nombre
      ruta
    }
  }
}

cURL Example

curl -X POST https://your-api-endpoint/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AZURE_AD_TOKEN" \
  -d '{
    "query": "mutation { authenticate { token usuario { id nombre email } } }"
  }'

Response

{
  "data": {
    "authenticate": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "usuario": {
        "id": 42,
        "nombre": "Juan Pérez",
        "email": "[e-mail]",
        "activo": true
      },
      "permisos": [
        {
          "id": 1,
          "idPermiso": 5,
          "permiso": {
            "nombre": "Gestión de Órdenes"
          }
        }
      ],
      "menu": [
        {
          "id": 1,
          "nombre": "Dashboard",
          "ruta": "/dashboard"
        }
      ]
    }
  }
}

The token is valid for 120 minutes (2 hours) from the time it’s issued. After expiration, you’ll need to re-authenticate.

Step 2: Make Your First Query

Now that you have a token, you can make queries to the API. Let’s fetch a list of users.

Query Example

query {
  getUsuarios {
    id
    nombre
    email
    activo
    rol {
      id
      nombre
      descripcion
    }
  }
}

cURL Example

curl -X POST https://your-api-endpoint/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SATELITE_JWT_TOKEN" \
  -d '{
    "query": "query { getUsuarios { id nombre email activo } }"
  }'

Response

{
  "data": {
    "getUsuarios": [
      {
        "id": 1,
        "nombre": "María González",
        "email": "[e-mail]",
        "activo": true,
        "rol": {
          "id": 2,
          "nombre": "Administrador",
          "descripcion": "Acceso completo al sistema"
        }
      },
      {
        "id": 2,
        "nombre": "Carlos Ramírez",
        "email": "[e-mail]",
        "activo": true,
        "rol": {
          "id": 3,
          "nombre": "Usuario",
          "descripcion": "Acceso estándar"
        }
      }
    ]
  }
}

Step 3: Execute a Mutation

Let’s create a new catalog entry using a mutation.

Mutation Example

mutation {
  createCatalogo(input: {
    nombre: "Nueva Categoría"
    descripcion: "Descripción de la categoría"
    estado: true
  }) {
    id
    nombre
    descripcion
    estado
  }
}

cURL Example

curl -X POST https://your-api-endpoint/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SATELITE_JWT_TOKEN" \
  -d '{
    "query": "mutation { createCatalogo(input: { nombre: \"Nueva Categoría\", descripcion: \"Descripción\", estado: true }) { id nombre } }"
  }'

Step 4: Query with Filtering and Sorting

The API supports advanced filtering and sorting using HotChocolate’s filtering capabilities.

Filtered Query Example

query {
  getUsuarios(
    where: { activo: { eq: true } }
    order: { nombre: ASC }
  ) {
    id
    nombre
    email
    activo
  }
}

Query with Nested Relations

query {
  getUsuarios {
    id
    nombre
    email
    rol {
      nombre
      descripcion
    }
  }
}

Common Query Patterns

Get Entity by ID

query {
  getUsuarioById(id: 42) {
    id
    nombre
    email
    activo
  }
}

Get Entities by Email

query {
  getUsuarioByEmail(mail: "[e-mail]") {
    id
    nombre
    email
  }
}

Get Related Data

query {
  getAllReembolsos {
    id
    estado
    detalles {
      id
      descripcion
      monto
    }
  }
}

Using GraphQL Clients

JavaScript/TypeScript

Using Apollo Client or similar:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://your-api-endpoint/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${token}`,
  },
});

const GET_USERS = gql`
  query GetUsers {
    getUsuarios {
      id
      nombre
      email
    }
  }
`;

const { data } = await client.query({ query: GET_USERS });

C#

Using StrawberryShake or HTTP client:

using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", token);

var query = new {
    query = "query { getUsuarios { id nombre email } }"
};

var content = new StringContent(
    JsonConvert.SerializeObject(query),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://your-api-endpoint/graphql",
    content
);

Python

Using gql library:

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url='https://your-api-endpoint/graphql',
    headers={'Authorization': f'Bearer {token}'},
    use_json=True,
)

client = Client(transport=transport, fetch_schema_from_transport=True)

query = gql("""
    query {
        getUsuarios {
            id
            nombre
            email
        }
    }
""")

result = client.execute(query)

Error Handling

The API returns GraphQL-compliant error responses:

{
  "errors": [
    {
      "message": "No tiene rol asignado. Por favor, contacte al administrador del sistema para que le asigne un rol",
      "extensions": {
        "code": "AUTH_NOT_AUTHORIZED"
      }
    }
  ]
}

Always check the errors array in the response. Even if data is present, errors may have occurred during execution.

Next Steps

Authentication Guide

Deep dive into JWT authentication and token management

GraphQL Overview

Learn about the GraphQL schema structure

API Reference

Explore all available queries and mutations

Error Handling

Learn how to handle errors gracefully

GraphQL Playground

You can explore the API interactively using the built-in GraphQL IDE. Navigate to:

https://your-api-endpoint/graphql

The IDE provides:

• Schema documentation
• Query autocompletion
• Query validation
• Response formatting

Make sure to set your authentication token in the HTTP headers section of the GraphQL IDE.