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:
Provide your Azure AD access token
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" : "[email protected] " , "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" : "[email protected] " , "activo" : true , "rol" : { "id" : 2 , "nombre" : "Administrador" , "descripcion" : "Acceso completo al sistema" } }, { "id" : 2 , "nombre" : "Carlos Ramírez" , "email" : "[email protected] " , "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 { getAllReembolsos { id estado detalles { id descripcion monto } } }
Using GraphQL Clients JavaScript/TypeScript
C#
Python
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 });
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 );
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.
