SSC Space Go Sandbox - Interface Control Document¶

Version: 1.3 Date: June 2026
Based on: SSC Space Go ICD v2.4

Document Information¶

Item	Details
Document Title	SSC Space Go Sandbox Interface Control Document
Version	1.4
Status	Released
Classification	External

Version History¶

Version	Date	Changes	Author
1.0	April 2026	Initial release	Robin Fjärem
1.1	May 2026	Added TT&C Gateway section; updated scope, architecture, and sandbox characteristics to reflect mock TM/TC contact execution	Robin Fjärem
1.2	May 2026	Added the availability check in the general scheduling process	Júlia Tribó Cabré
1.3	June 2026	Additional contact states added, see section 4.4 for all the possible states; Updated the section 4.3 about scheduling time constraints with the service tiers	Mathias Nilsson
1.4	June 2026	Updated booking horizons	Marcus Näslund

Associated Documents¶

Document Name	Scope	Related Sections
SSC Space Go ICD	Production system interface	All Contents
SSC Space Go API Reference	Detailed API endpoint documentation	Scheduling, TLE
SSC Space Go Onboarding Form	Customer Configuration Parameters	All Contents

1. Introduction and Scope¶

The SSC Space Go Sandbox is a dedicated test environment provided to customers during the onboarding phase to validate their integration with SSC Space Go APIs. This Interface Control Document (ICD) defines the customer interfaces available in the sandbox environment.

1.1 Purpose¶

The Sandbox enables customers to:

Test scheduling workflows and API integration
Validate authentication mechanisms
Understand resource constraints and scheduling behaviors
Develop and debug mission planning system integrations
Test TM/TC WebSocket integration against a mock ground station

without affecting production operations or requiring actual spacecraft configurations.

1.2 Scope¶

This ICD covers the following functionality available in the sandbox:

Contact scheduling (creation, retrieval, cancellation)
TLE management
Site and spacecraft information queries
Service configuration retrieval
TT&C WebSocket access (with mock telemetry and telecommanding)

Not included in the Sandbox:

Data Distribution (payload data delivery via S3)
Post Contact Reports
Contact execution against simulated ground stations

For production system capabilities, refer to the SSC Space Go ICD.

1.3 Access Period¶

Sandbox access is granted during the customer onboarding period
Access credentials are separate from production credentials
Access will be revoked once the customer is successfully onboarded to the production environment

1.4 API Base URL¶

https://sandbox.go.sscspace.com/api/v1

Note: All timing references in this document are in UTC according to CCSDS standards.

2. Sandbox Overview¶

The Sandbox provides a realistic testing environment that mirrors the production SSC Space Go scheduling system with specific adaptations for integration testing.

2.1 Sandbox Characteristics¶

The sandbox environment is designed to replicate production scheduling behavior while providing a safe testing space for customer integration development.

Available 24/7:

The sandbox is continuously available throughout the customer integration period
Provides consistent scheduling API access for development and testing

Production-Like Configuration:

All SSC Space Go ground station sites are available (SEES, USAK, CAIS, CLPA, AUWA)
Same resource constraints and capacity limits as production
Identical antenna and frequency band configurations
Realistic scheduling conflicts and insufficient capacity responses

2.2 How the Sandbox Differs from Production¶

While the sandbox closely mirrors production behavior, there are several key differences designed for testing purposes:

Mock Spacecraft Configuration:

The sandbox uses test spacecraft configurations
Actual spacecraft signal parameters are not required for sandbox testing
This allows testing of scheduling and TT&C workflows without needing production-ready spacecraft configurations

Mock Ground Stations:

Contacts are executed against a simulated ground station, not real hardware
The TT&C WebSocket interface behaves identically to production, but telemetry data is synthetically generated (see Section 6 for details)
No real RF link is established; telecommands are not radiated to an actual spacecraft

Simplified Scheduling Constraints:

Limited to scheduling one contact per spacecraft per site during any single pass opportunity
This constraint helps manage sandbox resource usage while still enabling comprehensive API testing

Periodic Data Reset:

All scheduled contacts and uploaded TLEs are automatically cleared from the system on a regular basis
Reset Schedule: Every Thursday at 00:00 UTC and Sunday at 00:00 UTC
This ensures the sandbox remains responsive and prevents accumulation of test data
Customers should account for this reset schedule when planning extended testing sessions

Sandbox Access Period:

The sandbox (including TT&C access) is available during the customer onboarding period only
Access will be revoked once the customer is successfully onboarded to the production environment

2.3 What Works the Same as Production¶

To ensure your integration will work seamlessly when transitioning to production, the following behaviors are identical:

✓ Authentication: Same OAuth 2.0 flows and token mechanisms
✓ API Endpoints: Identical REST API structure and request/response formats
✓ TLE Management: Same TLE upload and validation processes
✓ Resource Scheduling: Same capacity constraints and conflict detection
✓ Booking States: Complete state machine (NEW → PENDING → CONFIRMED/REJECTED → ONHOLD → CANCELLED)
✓ Cancellation Policy: Contacts can only be cancelled from ONHOLD state
✓ Error Responses: Same error codes and problem response formats
✓ Contact Duration Limits: Same minimum (1 minute) and maximum (12 minutes) contact durations
✓ Maximum Scheduling Horizon: Same 4-day advance booking limit
✓ TT&C WebSocket URLs: Same URL schema and connection lifecycle
✓ TT&C Protobuf Definitions: Identical TM and TC message formats
✓ Commanding States: Same STANDBY/READY state machine (STANDBY emitted every 10 seconds before contact starts)
✓ EndOfContact Event: Sent at contact completion over TM WebSocket

Note: The sandbox has a reduced minimum scheduling time (15 minutes instead of 1 hour) to enable faster testing iterations.

2.4 Recommended Testing Approach¶

To make the most of your sandbox access:

Start Simple: Begin with single contact requests to validate authentication and basic API calls
Test Edge Cases: Try scheduling conflicts, overlapping contacts, and capacity limits
Validate TLE Handling: Test TLE upload, retrieval, and freshness validation
Test State Transitions: Monitor contacts through various state changes
Test TT&C Integration: Connect to TM/TC WebSockets during a scheduled contact, verify STANDBY → READY transitions, receive mock TM data, and send TC commands
Account for Resets: Plan your testing around the Thursday/Sunday reset schedule
Verify Error Handling: Test your system's response to various error conditions (missing parameters, invalid credentials, scheduling conflicts)

Important: While the sandbox provides a realistic testing environment, always verify your integration against production documentation and confirm any assumptions with your SSC Space Go representative before going live.

3. Authentication and Authorization¶

The sandbox uses the same authentication mechanisms as the production SSC Space Go system. This ensures that authentication code developed and tested in the sandbox will work identically in production.

Note: Sandbox credentials are separate from production credentials and will be provided during the onboarding process.

3.1 Authentication Flow¶

The OAuth 2.0 Client Credentials flow is used for machine-to-machine authentication:

sequenceDiagram
    participant C as Client Application
    participant E as Authorization Server<br/>(Microsoft Entra ID)
    participant A as Sandbox API<br/>(/api/v1)

    C->>E: 1. Request Token<br/>(client_id, client_secret, scope)
    E->>E: 2. Validate client credentials
    E->>C: 3. Return token (JWT)
    C->>A: 4. Call API with token
    A->>C: 5. Return data

The response includes how long the token is valid for and lets you request a new token whenever the current one expires. The token will be short-lived.

3.2 OAuth 2.0 Configuration¶

Parameter	Description
Token URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
Scope	`api://{clientId}/.default`
Grant Type	`client_credentials`

Note: Specific values for {tenantId} and {clientId} for the sandbox environment will be provided during onboarding.

3.3 Required Scopes by Endpoint¶

The sandbox supports the same permission scopes as production:

Scope	Endpoints
`contacts.view`	GET /contacts, GET /contacts/{id}
`contacts.create`	POST /contacts
`contacts.cancel`	DELETE /contacts/{id}
`spacecraft.view`	GET /spacecraft, GET /spacecraft/{id}, GET /spacecraft/{id}/service-types/*/services
`sites.view`	GET /sites, GET /sites/{id}
`tle.view`	GET /spacecraft/{id}/tle
`tle.upload`	POST /spacecraft/{id}/tle

3.4 Using Access Tokens¶

Once you obtain an access token via the OAuth 2.0 Client Credentials flow (Section 3.1), include it in all API requests using the HTTP Authorization header with the Bearer scheme:

Authorization: Bearer <access_token>

Token Characteristics:

Tokens are short-lived (typically 60 minutes)
The token response includes an expires_in field indicating validity duration
Request a new token before the current one expires
The system ensures you can only access your assigned test spacecraft and services

Example Token Request:

curl -X POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={clientId}" \
  -d "client_secret={clientSecret}" \
  -d "scope=api://{clientId}/.default" \
  -d "grant_type=client_credentials"

Example API Request with Token:

curl -X GET https://{sandbox-endpoint}/api/v1/spacecraft \
  -H "Authorization: Bearer {access_token}"

Important: Keep your client credentials secure. Do not commit them to version control or share them publicly.

4. Scheduling API¶

This section specifies the scheduling functionality available in the sandbox environment. All scheduling functions are available through a RESTful web service API, enabling you to integrate and test your mission planning systems.

For detailed API endpoint documentation, see the SSC Space Go API Reference.

Terminology¶

Throughout this document, the term "contact" refers to a scheduled communication event between a spacecraft and a ground station:

Term	Definition
Mission	An organizational grouping of one or more spacecraft (e.g., a constellation or program)
Spacecraft	A single satellite belonging to a mission, identified by NORAD ID and unique spacecraft_id
Contact Request	A customer's request to schedule a contact (API: `POST /contacts`)
Contact	The scheduled communication window with associated resources and state
Contact ID	Unique identifier (UUID) assigned to a contact upon creation
Contact Window	The time period (start to end) during which the spacecraft is above the horizon mask

Note: Each spacecraft belongs to exactly one mission. The mission/spacecraft hierarchy supports constellation operations where multiple spacecraft share configuration and billing.

4.1 General Scheduling Process¶

The sandbox scheduling workflow mirrors the production system:

Customer Responsibilities:

Authenticate using OAuth 2.0 (see Section 3)
Provide a valid TLE for your test spacecraft
Calculate spacecraft visibilities to predict start (AOS) and stop (LOS) times
Poll the system to receive confirmation/rejection and check updated contact status

The SSC Space Go scheduling system factors in the availability of resources required to complete the contact service request.

sequenceDiagram
    participant C as Customer
    participant S as Sandbox Scheduler

    Note over C: Calculate visibility<br/>using TLE data
    C->>S: Upload TLE
    C->>S: GET /contacts/availability<br/>(Check Availability)
    S->>C: Return availability
    C->>S: POST /contacts<br/>(Request Contact)
    S->>S: Validate Request
    S->>C: 201 Created + contact_id (UUID)

    Note over C: Use contact_id to track progress

    loop Customer Polling
        C->>S: GET /contacts/{contact_id}
        S->>C: Return contact status
    end

    Note over S: Status: NEW → PENDING → CONFIRMED/REJECTED<br/>(confirmed contacts may later move to REVIEW or ONHOLD)

4.2 Contact Request Parameters¶

A booking request must specify the following parameters:

Parameter	Description
`site_id`	Site identifier (e.g., "SEES", "USAK", "CAIS", "CLPA", "AUWA")
`spacecraft_id`	Spacecraft identifier (crucial for constellation management)
`start`	Contact start time in ISO 8601 format, rounded down to the closest minute
`end`	Contact end time in ISO 8601 format, rounded up to the closest minute
`service`	Contact service configuration object containing the service `id`

Upon reception of a valid contact request, you receive a response with a contact_id (UUID) that enables:

Tracking the progress of the contact request
Polling the system to receive confirmation/rejection
Continuously checking the updated status of the contact

Example Request:

{
  "site_id": "SEES",
  "spacecraft_id": "test-sat-01",
  "start": "2026-04-20T10:00:00Z",
  "end": "2026-04-20T10:10:00Z",
  "service": {
    "id": "test-service-config-id"
  }
}

Example Response:

{
  "contact_id": "550e8400-e29b-41d4-a716-446655440000"
}

4.3 Scheduling Time Constraints¶

The sandbox uses slightly different time constraints to facilitate easier testing:

Constraint	Sandbox Value	Production Value
Minimum Schedule Request Time	15 minutes before contact	1 hour before contact
Minimum Contact Duration	1 minute	1 minute
Maximum Contact Duration	12 minutes	12 minutes

The maximum schedule request horizon is determined by the service tier assigned to each spacecraft during onboarding. Three tiers are available — BASIC, ADVANCED, and PREMIUM — each offering a different scheduling horizon as shown below.

Service Tier	Maximum Schedule Request Horizon
BASIC	2 days in advance
ADVANCED	4 days in advance
PREMIUM	10 days in advance

Note: The reduced minimum scheduling time (15 minutes instead of 1 hour) in the sandbox allows for more rapid testing cycles.

4.4 Booking States¶

Since a contact request is for an anticipated event, there are different schedule states. A confirmed contact could also update/change state depending on resource constraints. It is your responsibility to poll and check for the latest state.

stateDiagram-v2
    [*] --> NEW: Contact Request
    NEW --> PENDING: Resources Available
    NEW --> REJECTED: No Resources
    PENDING --> CONFIRMED: Site Confirmed
    CONFIRMED --> REVIEW: Issue Detected
    CONFIRMED --> ONHOLD: Service Unavailable
    REVIEW --> CONFIRMED: Issue Resolved
    ONHOLD --> CONFIRMED: Issue Resolved
    ONHOLD --> CANCELLED: Customer Cancel
    CONFIRMED --> ONGOING: Contact in progress
    ONGOING --> POST_CONTACT: Contact is over
    CANCELLED --> [*]
    REJECTED --> [*]
    POST_CONTACT --> SUCCESS
    POST_CONTACT --> PARTIAL_SUCCESS 
    POST_CONTACT --> FAIL
    POST_CONTACT --> UNKNOWN: All internal data is not avail
    UNKNOWN --> UNKNOWN
    UNKNOWN --> SUCCESS
    UNKNOWN --> PARTIAL_SUCCESS
    UNKNOWN --> FAIL

State	Description
`NEW`	Contact request received and being processed
`PENDING`	Resources identified, awaiting site confirmation
`CONFIRMED`	Contact confirmed, resources locked
`REJECTED`	Insufficient resources for requested period
`REVIEW`	Issues identified that may impact service quality (e.g., old TLE). Service will still be provided but might be degraded
`ONHOLD`	Service is unavailable due to internal service issues; customer may cancel or wait for resolution
`CANCELLED`	Contact has been cancelled by the customer
`ONGOING`	Contact is currently running
`POST_CONTACT`	The contact has ended; outcome validation is in progress
`SUCCESS`	All services for the contact started successfully
`PARTIAL_SUCCESS`	Some, but not all, services for the contact started successfully
`FAIL`	No services for the contact started successfully
`UNKNOWN`	Assessment data is not yet fully available

Important: Contact cancellation requests can only be made when the contact is in an ONHOLD state. No other contact state shall allow the customer to request a contact cancellation.

Note: If SSC Space Go resolves the issue before the contact starts, the contact will automatically transition back to CONFIRMED without any action required from you. If you choose to keep the contact, continue polling via GET /contacts/{id} to monitor the state.

Cancellation Policy:

Customers cannot directly cancel contacts in CONFIRMED, PENDING, or REVIEW states
The ONHOLD state is set by SSC Space Go when there are internal service issues that will prevent service delivery
Once a contact transitions to ONHOLD, you can decide to cancel via DELETE /contacts/{id}

4.5 API Endpoints Summary¶

The following endpoints are available in the sandbox:

Method	Endpoint	Description
POST	`/contacts`	Create a new contact request
GET	`/contacts`	List contacts (with optional filters)
GET	`/contacts/{contact_id}`	Get specific contact details
DELETE	`/contacts/{contact_id}`	Cancel a contact (ONHOLD only)
GET	`/spacecraft`	List available test spacecraft
GET	`/spacecraft/{spacecraft_id}`	Get spacecraft details
GET	`/spacecraft/{spacecraft_id}/service-types/{type}/services`	List service configurations
GET	`/spacecraft/{spacecraft_id}/service-types/{type}/services/{service_id}`	Get service configuration details
GET	`/sites`	List available ground station sites
GET	`/sites/{site_id}`	Get site details

For complete request/response schemas and examples, see the SSC Space Go API Reference.

4.6 Sandbox-Specific Scheduling Constraints¶

In addition to the standard scheduling constraints, the sandbox enforces the following limitation:

Single Contact Per Pass:

You can only schedule one contact per spacecraft per site during any single pass opportunity
Attempting to schedule multiple overlapping contacts for the same spacecraft at the same site will result in a resource conflict error
This constraint helps manage sandbox resource usage while enabling comprehensive API testing

Example:

If you have scheduled a contact for TEST-SAT-01 at SEES from 10:00:00 to 10:10:00, you cannot schedule another contact for the same spacecraft at the same site with overlapping times (e.g., 10:05:00 to 10:15:00).

You can, however: - Schedule contacts for TEST-SAT-01 at different sites (e.g., USAK) - Schedule contacts for different spacecraft at SEES - Schedule sequential contacts for TEST-SAT-01 at SEES (e.g., next pass)

4.7 Testing Workflow Recommendations¶

To effectively test your scheduling integration:

Query Available Resources:
GET /spacecraft - Identify your test spacecraft
GET /sites - List available ground station sites
GET /spacecraft/{id}/service-types/{type}/services - Get available service configurations
Upload TLE Data:
POST /spacecraft/{id}/tle - Upload valid TLE for orbit propagation
Create Contact Requests:
POST /contacts - Submit contact requests with calculated visibility windows
Verify you receive a contact_id in the response
Monitor Contact Status:
GET /contacts/{contact_id} - Poll to check state transitions
Test handling of various states (NEW, PENDING, CONFIRMED, REJECTED)
Test Conflict Scenarios:
Submit overlapping requests to trigger resource conflicts
Verify your system correctly handles REJECTED responses
Test Cancellation:
If a contact enters ONHOLD state, test the cancellation flow
DELETE /contacts/{id} - Verify cancellation succeeds only in ONHOLD state

5. TLE Management¶

The sandbox requires valid Two-Line Element (TLE) data for test spacecraft to enable accurate orbit propagation during scheduling. The TLE management functionality in the sandbox works identically to the production system.

For detailed TLE API endpoint documentation, see the SSC Space Go API Reference.

5.1 TLE Requirements¶

You are responsible for uploading and maintaining current TLE data for your test spacecraft
TLE data is used by the scheduling system to validate contact times against spacecraft visibility
The system validates TLE epoch freshness against scheduled contact times

TLE Freshness Guidelines:

Condition	System Behavior
TLE epoch within 48 hours of contact	Normal processing
TLE epoch older than 48 hours	Contact may be placed in `REVIEW` state
TLE epoch significantly outdated	Contact may be rejected

Recommendation: Upload fresh TLE data regularly during your testing to validate how your system handles TLE freshness checks and REVIEW state transitions.

5.2 TLE Data Format¶

TLE data follows the standard two-line format:

{
  "line1": "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927",
  "line2": "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
}

5.3 TLE API Endpoints¶

Method	Endpoint	Description
POST	`/spacecraft/{id}/tle`	Upload TLE for a spacecraft
GET	`/spacecraft/{id}/tle`	Retrieve current TLE

Example TLE Upload:

curl -X POST https://{sandbox-endpoint}/api/v1/spacecraft/TEST-SAT-01/tle \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "1 25544U 98067A   26106.51782528 -.00002182  00000-0 -11606-4 0  2927",
    "line2": "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
  }'

Example TLE Retrieval:

curl -X GET https://{sandbox-endpoint}/api/v1/spacecraft/TEST-SAT-01/tle \
  -H "Authorization: Bearer {access_token}"

5.4 Testing TLE Management¶

Use the sandbox to test the following TLE-related scenarios:

Upload Valid TLE: Verify successful TLE upload for your test spacecraft
Retrieve TLE: Confirm you can retrieve the uploaded TLE data
Test Stale TLE: Upload an old TLE and schedule a contact to see REVIEW state behavior
Update TLE: Upload a newer TLE to replace an existing one
TLE Validation: Test how the system responds to malformed TLE data

Note: Remember that TLE data is cleared during the periodic sandbox resets (Thursday and Sunday at 00:00 UTC). You will need to re-upload TLE data after each reset.

6. TT&C Gateway¶

The TT&C sandbox provides a mock TT&C Gateway at each ground station site, allowing you to test your Mission Control Center's WebSocket integration without any real hardware or spacecraft. The WebSocket interface behaves identically to production – the same URLs, authentication, protobuf message definitions, and connection lifecycle apply.

For the complete TT&C protobuf definitions and URL schema, see Section 6 of the SSC Space Go ICD.

6.1 Overview¶

flowchart LR
    subgraph Customer["Customer MCC"]
        TMC["TM Client"]
        TCC["TC Client"]
    end

    subgraph Sandbox["Sandbox Ground Station Site"]
        TTCGW["TT&C Gateway"]
        MOCK["Mock Ground Station\n(Simulated Hardware)"]
    end

    TMC <-->|"WebSocket/Protobuf\nTM Service (v2)"| TTCGW
    TCC <-->|"WebSocket/Protobuf\nTC Service (v2)"| TTCGW
    TTCGW <-->|"Internal"| MOCK

The sandbox TT&C Gateway operates identically to production from the customer's perspective. The key difference is that the backend is connected to simulated hardware rather than a real antenna and modem.

Sandbox TT&C is available at all sites: SEES, USAK, CAIS, CLPA, AUWA. Site-specific gateway URLs are provided during onboarding.

6.2 Connection Lifecycle¶

The TT&C connection lifecycle in the sandbox is identical to production:

sequenceDiagram
    participant C as Customer
    participant GW as TT&C Gateway (Sandbox)
    participant M as Mock Hardware

    Note over GW,M: Service instantiated<br/>~minutes before contact
    C->>GW: WebSocket Connect + Auth Token
    GW->>GW: Validate Token
    GW->>C: Connection Established

    Note over C: Contact not yet started<br/>STANDBY emitted every 10 seconds
    GW->>C: CommandingStatusUpdate (STANDBY)
    GW->>C: CommandingStatusUpdate (STANDBY)

    Note over GW,M: Contact Starts
    GW->>C: CommandingStatusUpdate (READY)
    M->>GW: Mock TM Data
    GW->>C: Stream TM Data (TmDataMsg)
    C->>GW: TC Request
    GW->>M: Forward TC
    GW->>C: TcReceivedAck
    GW->>C: TcRadiationAck

    Note over GW: Contact End
    GW->>C: EndOfContact
    GW->>C: Connection Closed

6.3 Telemetry (TM) Service¶

The TM service in the sandbox streams synthetically generated telemetry data that matches the TM_TYPE_OTHER protobuf format. This allows you to validate your TM parsing pipeline without a real spacecraft signal.

Mock TM Characteristics:

Field	Sandbox Value	Notes
`tm_type`	`TM_TYPE_OTHER`	VITA-49 formatted data
`frame_quality`	`TM_FRAME_QUALITY_UNSPECIFIED`	Quality reporting not applicable for synthetic data
`tm_data`	Synthetically generated VITA-49 packets	Details communicated during onboarding
Data rate	~1 Mbps	Pre-determined by SSC Space; not configurable by the customer
`LossFrameSyncNotif`	Not sent	Not applicable for simulated hardware
`EndOfContact`	Sent at contact completion	Identical to production

Service Characteristics:

Service instantiated minutes before scheduled contact start
Maximum 2 concurrent connections per TM service
TM streaming begins when the contact starts (READY state)
EndOfContact event is sent at contact completion, followed by connection closure

TM URL Schema:

wss://<station_base_url>/v2/<spacecraft_id>/<site_id>/tm?format=proto

Note: The tm_data bytes in each TmDataMsg are VITA-49 packets generated by SSC Space's sandbox system. The exact VITA-49 structure will be shared with you during onboarding so you can validate decoding in your system.

6.4 Telecommand (TC) Service¶

The TC service in the sandbox accepts commands and returns the same acknowledgement sequence as production. Commands are forwarded to the simulated hardware, which returns radiation acknowledgements. No real uplink occurs.

TC URL Schema:

wss://<station_base_url>/v2/<spacecraft_id>/<site_id>/tc?format=proto

Service Characteristics:

Service instantiated minutes before scheduled contact start
Maximum 1 connection per TC service
Maximum command size: 65,335 bytes
Same tcId / expectedTcId sequence number enforcement as production

Commanding States:

State	Description
`STANDBY`	Emitted every 10 seconds while waiting for the contact to start
`READY`	Emitted when the contact starts and the mock hardware is connected

Note: The STANDBY state maps to COMMANDING_STATUS_STANDBY in the protobuf. Commands sent in STANDBY state are rejected with TC_RECEPTION_ERROR_OUT_OF_PROVISION_TIME.

What the sandbox returns for TC commands:

TcReceivedAck – immediate acknowledgement of command reception (same as production)
TcRadiationAck – returned by mock hardware once the command is processed (same protocol as production, no real radiation)

Command Queue:

Property	Value
Queue Size	100 commands maximum
Queue Type	Per-connection FIFO
Overflow Behavior	New commands rejected with `TC_RECEPTION_ERROR_TC_BUFFER_FULL`

6.5 Testing TT&C Integration¶

To test your TT&C integration in the sandbox:

Schedule a contact using the scheduling API (see Section 4)
Wait for confirmation — poll GET /contacts/{id} until the contact is CONFIRMED
Connect to the TM WebSocket before the scheduled contact start time
Connect to the TC WebSocket before the scheduled contact start time
Observe STANDBY state — the TC WebSocket will emit STANDBY every 10 seconds until the contact starts
Contact starts — both services become active; TC transitions to READY; TM data begins flowing
Send TC commands — verify TcReceivedAck and TcRadiationAck responses
Receive TM data — verify your TM parsing handles TM_TYPE_OTHER + TM_FRAME_QUALITY_UNSPECIFIED
Contact ends — EndOfContact is sent on the TM WebSocket, both connections are closed

Important: You must have a CONFIRMED contact before the TT&C WebSocket services become available. The services are instantiated by the system a few minutes before the scheduled contact start time.

6.6 WebSocket Close Codes¶

The sandbox uses the same WebSocket close codes as production:

Code	Name	Description
`1000`	Normal Closure	Graceful shutdown after EndOfContact or client-initiated close
`1011`	Internal Server Error	Server-side error during message processing

7. Error Handling¶

This chapter describes the error handling mechanisms in place within the sandbox environment, including common error responses and troubleshooting tips.

7.1 Error Response Format¶

All error responses from the SSC Space Go APIs use the application/problem+json format as defined in RFC 7807, making it easier to programmatically handle errors in your integration:

{
  "title": "Invalid Request",
  "detail": "The 'site_id' parameter is required but was not provided",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Fields:

Field	Type	Description
`title`	string	Short summary of the problem
`detail`	string	Detailed description of the problem
`trace_id`	string	Unique identifier (UUID) for tracking this request

Tip: Include the trace_id when contacting SSC Space Go support for faster issue resolution.

7.2 HTTP Status Codes¶

The sandbox API uses standard HTTP status codes:

Status Code	Description
`200`	Success
`201`	Created (successful contact creation)
`204`	No Content (successful deletion)
`400`	Bad Request - Invalid input
`401`	Unauthorized - Authentication required
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`500`	Internal Server Error

Note: Error responses (4xx and 5xx) include a JSON body in application/problem+json format with details about the error.

7.3 Troubleshooting Tips¶

Common Issues:

Authentication Errors (401): Verify your access token is valid and hasn't expired. Request a new token using the OAuth 2.0 flow.
Missing Parameters (400): Check that all required fields (site_id, spacecraft_id, start, end, service) are included in your request.
Resource Not Found (404): Confirm the spacecraft ID, site ID, or contact ID exists and you have permission to access it.
Scheduling Conflicts: Remember the sandbox constraint of one contact per spacecraft per site per pass.
WebSocket connection refused: The TT&C service is not yet instantiated. Wait until closer to the scheduled contact start time and verify the contact is CONFIRMED.
TC commands rejected with TC_RECEPTION_ERROR_OUT_OF_PROVISION_TIME: The contact has not started yet. Wait for the READY commanding status before sending commands.
TC commands rejected with TC_RECEPTION_ERROR_COMMAND_STATUS_NOT_READY: The commanding status is still STANDBY. Wait for the READY commanding status update.

Best Practices:

Always check the detail field in error responses for specific information about what went wrong
Include the trace_id when reporting issues to SSC Space Go support
Verify request payloads match the expected schema before submitting

Note: Error handling behaviors are identical in the sandbox and production environments, allowing you to test and validate your error handling logic comprehensively.

8. Appendix¶

8.1 Acronyms¶

Acronym	Definition
AOS	Acquisition of Signal
API	Application Programming Interface
CCSDS	Consultative Committee for Space Data Systems
ICD	Interface Control Document
JWT	JSON Web Token
LOS	Loss of Signal
MCC	Mission Control Center
NORAD	North American Aerospace Defense Command
TC	Telecommand
TLE	Two-Line Element
TM	Telemetry
TT&C	Telemetry, Tracking & Command
UTC	Coordinated Universal Time
UUID	Universally Unique Identifier
VITA-49	VITA Standards Organization Radio Transport Protocol (VRT)

8.2 API Quick Reference¶

For complete API endpoint documentation including request/response schemas, see the SSC Space Go API Reference.

Method	Endpoint	Description
GET	`/contacts`	List contacts
POST	`/contacts`	Create contact
GET	`/contacts/{id}`	Get contact
DELETE	`/contacts/{id}`	Cancel contact (ONHOLD only)
GET	`/spacecraft`	List spacecraft
GET	`/spacecraft/{id}`	Get spacecraft
GET	`/spacecraft/{id}/tle`	Get TLE
POST	`/spacecraft/{id}/tle`	Upload TLE
GET	`/spacecraft/{id}/service-types/{type}/services`	List services
GET	`/spacecraft/{id}/service-types/{type}/services/{service_id}`	Get service configuration
GET	`/sites`	List sites
GET	`/sites/{id}`	Get site

TT&C WebSocket Endpoints (per site, URL provided during onboarding):

Service	URL Schema	Description
TM	`wss://<station_base_url>/v2/<spacecraft_id>/<site_id>/TM?format=protobuf`	Telemetry stream
TC	`wss://<station_base_url>/v2/<spacecraft_id>/<site_id>/TC?format=protobuf`	Telecommand channel