Building a Football Agent with Microsoft Copilot Studio and futebol.org
REST API Documentation, OpenAPI, Authentication, Tools, Orchestration, and Security
Introduction
A practical way to understand REST API Tools in Microsoft Copilot Studio is to design an Agent around a real external information domain.
For this study, we will use:
futebol.org
as the conceptual external football data provider for an Agent capable of answering questions about football information.
Our objective is not simply to make an HTTP request.
The objective is to understand the complete integration chain:
API Documentation
↓
Endpoints
↓
HTTP Methods
↓
Request Parameters
↓
Authentication
↓
Responses
↓
OpenAPI
↓
Copilot Studio REST API Tool
↓
Generative Orchestration
↓
Agent Response
This distinction is important because integrating an API into an Agent requires much more than knowing an endpoint URL.
The Agent needs a structured contract explaining what operations exist, what parameters they require, what they return, and how the external system authenticates requests.
Microsoft Copilot Studio currently provides a REST API Tool capability for exactly this type of architecture. Microsoft currently documents the feature as Preview, so it should be treated as a learning and experimentation capability until its production suitability is reevaluated against current Microsoft documentation.
1. Our Scenario
Imagine an Agent called:
Football Data Companion
The user could ask questions such as:
“Show me information about team 123.”
“Get the latest available matches for this competition.”
“Show me the details of match 456.”
“Which teams are participating in this competition?”
“Get the standings for this competition.”
The important architectural characteristic is that this information isn’t necessarily stored inside the Agent.
Instead, the Agent obtains live or externally maintained information from futebol.org.
Conceptually:
User
↓
Football Data Companion
↓
Generative Orchestration
↓
futebol.org Tool
↓
REST API
↓
Football Data
↓
Agent
↓
Natural-language response
This differs fundamentally from a Knowledge Source.
2. Knowledge vs API
Suppose we give the Agent a document explaining football competition rules.
Question:
“How does this competition’s scoring system work?”
This could be:
Knowledge
↓
Retrieval
↓
Grounding
↓
Answer
But suppose the user asks:
“What data does futebol.org currently return for match 456?”
That potentially requires:
Agent
↓
REST API Tool
↓
futebol.org
↓
Current API response
↓
Agent
↓
Answer
Therefore:
Knowledge = information available for retrieval
while:
REST API Tool = capability to interact with an external service
This distinction remains fundamental throughout Copilot Studio architecture.
3. Start with API Documentation, Not Copilot Studio
One of the easiest mistakes when learning Agent integration is immediately opening:
Copilot Studio → Tools → Add a tool → REST API
before understanding the external API.
The correct architecture begins outside Copilot Studio.
First we must understand:
What exactly does the API provide?
The proper sequence is:
API Documentation
↓
Understand API
↓
Understand Authentication
↓
Test API
↓
Understand Request
↓
Understand Response
↓
Define OpenAPI
↓
Import into Copilot Studio
↓
Create Tools
↓
Test Agent
Copilot Studio should not be the place where we discover how an undocumented API behaves through trial and error.
4. What We Need from futebol.org Documentation
Before creating anything, we should locate authoritative documentation describing at least:
| Information | What We Need to Discover |
|---|---|
| Base URL | Root address of the API |
| Endpoints | Available resources |
| HTTP Methods | GET, POST, PUT, PATCH, DELETE |
| Parameters | IDs, dates, competitions, teams, etc. |
| Authentication | None, API key, OAuth 2.0, or another mechanism |
| Headers | Required HTTP headers |
| Query parameters | Filtering and paging options |
| Request schema | JSON sent to the API |
| Response schema | JSON returned by the API |
| Error responses | 400, 401, 403, 404, 429, 500, etc. |
| Rate limits | Request limits |
| Pagination | How large result sets are returned |
| OpenAPI | Whether an official specification exists |
| Terms of use | Whether Agent/API usage is permitted |
This information forms the API contract.
5. Important Documentation Status
At the time of preparing this article, publicly indexed search results did not provide authoritative futebol.org documentation confirming the API endpoints or authentication mechanism required for our integration.
Therefore, this article deliberately does not claim that futebol.org uses:
- API keys
- OAuth 2.0
- Bearer tokens
- Specific endpoints
- Specific scopes
until those details are confirmed from the provider’s actual documentation.
This is an important engineering principle:
Never design authentication from assumptions.
We first discover the API contract.
Then we implement it.
6. Documentation Discovery
For our real laboratory, the first technical investigation should answer:
Does futebol.org provide:
API Documentation?
Does it provide:
Swagger?
Does it provide:
OpenAPI?
Does it expose something such as:
swagger.json
or:
openapi.json
Does it document authentication?
Does it require account registration?
Does it issue an API credential?
These questions must be answered before the Agent architecture is finalized.
7. Why OpenAPI Matters
Microsoft Copilot Studio doesn’t simply receive an arbitrary list of URLs.
For a REST API Tool, Microsoft requires an OpenAPI specification describing the API.
Microsoft currently states that REST API Tools are created from an OpenAPI v2 specification.
If OpenAPI v3 is supplied, Copilot Studio automatically translates it to v2 because of the way Power Platform processes API specifications.
Therefore:
futebol.org Documentation
↓
API Contract
↓
OpenAPI
↓
Copilot Studio
↓
REST API Tools
OpenAPI becomes the bridge between the football API and the Agent.
8. If futebol.org Already Provides OpenAPI
The ideal scenario is:
futebol.org
↓
Official OpenAPI
↓
Download specification
↓
Review specification
↓
Import into Copilot Studio
This reduces manual work.
But we still need to inspect the specification.
Never import a large OpenAPI file blindly.
We should understand what capabilities we are exposing to the Agent.
9. If futebol.org Does Not Provide OpenAPI
A second scenario is:
API documentation exists
but:
OpenAPI specification does not exist.
Then we can create our own OpenAPI definition based on the official documentation.
Conceptually:
Official API Documentation
↓
Endpoints
↓
Parameters
↓
Authentication
↓
Response Schemas
↓
Our OpenAPI Specification
↓
Copilot Studio
This is perfectly reasonable when the API contract is sufficiently documented.
However, our specification must reflect the actual API.
We should not invent behavior simply to make Copilot Studio accept the API.
10. Hypothetical Football API
To understand the architecture without falsely attributing undocumented endpoints to futebol.org, imagine that the provider documented operations equivalent to:
Get Team
Get Match
Search Matches
Get Competition
Get Standings
These are conceptual operations.
They might correspond to HTTP endpoints such as:
GET /teams/{id}
GET /matches/{id}
GET /matches
GET /competitions/{id}
GET /competitions/{id}/standings
Again, these endpoint paths are examples for architecture discussion.
They must not be treated as confirmed futebol.org endpoints until verified against its official API documentation.
11. API Operations Become Agent Tools
Once described through OpenAPI, operations can become Copilot Studio Tools.
For example:
API operation:
Get Match
↓
Copilot Studio Tool:
GetMatch
Another:
API operation:
Get Team
↓
Tool:
GetTeam
Another:
API operation:
Get Standings
↓
Tool:
GetStandings
The Agent then has semantic capabilities rather than merely URLs.
12. Why This Matters for Generative Orchestration
Suppose our Agent has:
GetTeam
GetMatch
SearchMatches
GetCompetition
GetStandings
The user asks:
“Show me the table for competition 10.”
The Agent must determine:
Which Tool should I use?
Conceptually:
User Prompt
↓
Generative Orchestration
↓
Available Tools
↓
Analyze names + descriptions + parameters
↓
Select GetStandings
↓
Call API
Microsoft explicitly states that descriptions help the language model determine when an API should be invoked.
This makes API documentation part of Agent orchestration.
13. Tool Descriptions Are Extremely Important
Consider this poor description:
GetData
Description:
“Gets football data.”
Now compare:
GetCompetitionStandings
Description:
“Retrieves the current available standings for a specified football competition using its competition identifier.”
The second description provides semantic information that Generative Orchestration can use.
This is why Tool descriptions are not cosmetic documentation.
They participate in Tool selection.
14. Parameter Documentation Is Equally Important
Suppose the Tool requires:
competitionId
Poor description:
“ID”
Better description:
“The unique identifier of the football competition whose standings should be retrieved.”
Suppose another parameter is:
season
Better description:
“The season associated with the requested competition data, using the format supported by the API.”
We should avoid assuming a format until the provider documentation defines it.
15. The OpenAPI Contract
Conceptually, our OpenAPI specification would describe:
Host
Base path
Schemes
Authentication
Paths
Operations
Parameters
Responses
Definitions
The simplified architecture becomes:
Copilot Studio
↓
OpenAPI Contract
↓
HTTP Request
↓
futebol.org
↓
JSON Response
↓
Tool Output
↓
Agent
16. HTTP Methods
Football information APIs are frequently read-oriented.
For our Agent, we may primarily need:
GET
Examples conceptually include:
Get team
Get match
Get competition
Get standings
Get fixtures
However, we must verify what futebol.org actually supports.
If the API is read-only, that can be advantageous from a security perspective.
The Agent cannot accidentally modify football data through the API.
17. Read-Only Agent Architecture
If every Tool is GET-based:
Agent
↓
REST Tool
↓
GET
↓
Football API
↓
Response
the primary security risk is:
information access
rather than:
business data modification
This significantly reduces the Agent’s blast radius compared with Tools exposing:
POST
PATCH
PUT
DELETE
18. Authentication Discovery
Authentication is one of the most important parts of our laboratory.
Before configuring Copilot Studio, we need to determine exactly what futebol.org expects.
Possible API designs include:
No authentication
API key
Bearer token
OAuth 2.0
Custom authentication
But only the provider documentation can tell us which is correct.
19. Copilot Studio Authentication Options
Microsoft currently documents three authentication choices when configuring a REST API Tool:
None
API key
OAuth 2.0
The selection determines how Copilot Studio establishes access to the external system.
Therefore, once we discover futebol.org authentication, we map it to the appropriate Copilot Studio mechanism.
20. Scenario A — No Authentication
If futebol.org documented a public endpoint requiring no credentials:
Copilot Studio
↓
REST Tool
↓
HTTP GET
↓
futebol.org
↓
Response
In Copilot Studio:
Authentication:
None
This is the simplest scenario.
However, public API access can still involve:
- Rate limits
- Acceptable-use policies
- IP restrictions
- Usage quotas
- Licensing restrictions
“No authentication” does not mean “unlimited use.”
21. Scenario B — API Key
Suppose the provider documentation states that requests require:
X-API-Key
Then the HTTP architecture could be:
GET /resource
Header:
X-API-Key: ********
Copilot Studio would be configured with:
Authentication:
API key
Parameter name:
X-API-Key
Parameter location:
Header
Microsoft documents API key authentication for REST API Tools and allows the key to be supplied through a Header or Query parameter. At runtime, the Agent can prompt the user to authenticate by supplying the key.
22. Header vs Query Parameter
An API key could theoretically be transmitted as:
Header:
X-API-Key: secret
or:
Query:
?api_key=secret
Which one we use is not our architectural preference.
It must match the provider’s API contract.
If futebol.org says:
Header
we configure Header.
If it says:
Query
we configure Query.
Never arbitrarily change the authentication protocol.
23. API Key Security
An API key is a credential.
It must not be placed in:
Agent Instructions
Knowledge Sources
User-visible prompts
Source code repositories
Screenshots
Documentation examples containing the real value
Instead, the platform’s authentication mechanism should handle it.
The distinction is:
Tool description:
Public metadata
Credential:
Secret
These should remain separate.
24. API Key Identity Limitation
API keys introduce another architectural question.
Imagine:
Edvaldo
↓
Football Agent
and:
Another User
↓
Football Agent
If both ultimately access futebol.org through the same credential, the external API may not distinguish the human users.
Conceptually:
User A ─┐
User B ─┼→ Agent → Shared API Credential → futebol.org
User C ─┘
This may be perfectly acceptable for public football information.
It would be much more problematic for sensitive enterprise information.
25. Scenario C — OAuth 2.0
Suppose instead the API documentation requires OAuth 2.0.
The architecture changes considerably:
User
↓
Agent
↓
Authorization Endpoint
↓
Identity Provider
↓
User Authentication
↓
Authorization Code
↓
Token Endpoint
↓
Access Token
↓
REST API
OAuth allows access to be tied more closely to an authenticated identity.
26. OAuth Fields in Copilot Studio
Microsoft currently documents configuration including:
Client ID
Client Secret
Authorization URL
Token URL
Refresh URL
Scope
Microsoft 365 organization restrictions
Client application restrictions.
These fields must come from the actual OAuth provider configuration.
They cannot be invented by Copilot Studio.
27. Client ID
The Client ID identifies the application.
Conceptually:
Identity Provider:
“Which application is requesting authorization?”
↓
Client ID
It normally isn’t considered a secret.
28. Client Secret
The Client Secret proves the identity of a confidential client.
Conceptually:
Client ID
Client Secret
↓
OAuth Token Infrastructure
The Client Secret is sensitive.
It should be protected and rotated according to the provider’s security requirements.
29. Authorization URL
The Authorization URL is where the user is directed to authenticate and grant authorization.
Conceptually:
Agent
↓
Authorization URL
↓
Login
↓
Consent
↓
Authorization Code
The user’s password is handled by the identity provider, not by our Agent.
30. Token URL
The authorization code is then exchanged:
Authorization Code
↓
Token URL
↓
Access Token
The Agent can then call the API using that token.
31. Access Token
Conceptually, an authenticated API call may look like:
HTTP Request
↓
Authorization:
Bearer AccessToken
↓
futebol.org API
↓
Validate Token
↓
Return Data
Again, this is the generic OAuth model.
We must confirm whether futebol.org actually implements it before using it in our laboratory.
32. Scopes
OAuth APIs can define permissions such as conceptually:
football.read
matches.read
competitions.read
profile.read
These examples are hypothetical.
If scopes exist, we should request only those needed by the Agent.
This applies the principle of:
Least Privilege
33. Why Authentication Must Be Studied Separately
There are actually several different questions:
Authentication
Who or what is connecting?
Authorization
What is that identity allowed to do?
Credential
What proves identity?
Scope
What permissions are being requested?
Connection
What runtime context does Copilot Studio use?
These concepts should not be collapsed into the single word “login.”
34. Testing the API Before the Agent
Before introducing Copilot Studio, we should test the API independently.
Conceptually:
Browser / REST Client / Script
↓
API Request
↓
futebol.org
↓
Response
We should confirm:
HTTP status
Response JSON
Authentication
Required headers
Parameters
Error behavior
Only after that should we introduce the Agent.
This isolates variables.
35. Why This Matters for Troubleshooting
Imagine Copilot Studio returns an error.
Without independent API testing, we don’t know whether the problem is:
Agent
OpenAPI
Authentication
Endpoint
Parameter
API
Credential
Rate limit
But if the API has already been tested independently:
API works
↓
OpenAPI works
↓
Then investigate Copilot Studio
This dramatically reduces troubleshooting complexity.
36. Inspecting the JSON Response
Suppose an API response conceptually contains:
Match ID
Home Team
Away Team
Home Score
Away Score
Competition
Date
Status
We should inspect:
Property names
Data types
Nested objects
Arrays
Null values
Date formats
Identifiers
The OpenAPI response schema should accurately represent these structures.
37. JSON Becomes Tool Output
Conceptually:
futebol.org
↓
JSON
↓
REST API Tool Output
↓
Agent Context
↓
Generated Response
For example:
API:
Structured JSON
Agent:
“Team A defeated Team B 2–1.”
The Agent transforms structured machine data into conversational output.
38. Structured Response vs Adaptive Card
Our Football Agent can go one step further.
Instead of always returning plain text:
REST API
↓
JSON
↓
Agent
↓
Text
we could design:
REST API
↓
JSON
↓
Agent
↓
Adaptive Card
This could be useful for:
Match cards
Team summaries
Standings
Competition information
Fixtures
The REST API supplies data.
The Adaptive Card supplies presentation.
These are separate architectural responsibilities.
39. Example Match Card Architecture
User:
“Show match 456.”
↓
GetMatch Tool
↓
futebol.org
↓
JSON
↓
Agent
↓
Adaptive Card
↓
Home Team
Away Team
Score
Competition
Date
Status
This creates a much richer football Agent experience.
40. REST API Tool vs HTTP Request Node
Copilot Studio also supports an HTTP Request node inside Topics.
Microsoft documents support for:
GET
POST
PATCH
PUT
DELETE.
Therefore, we potentially have two different architectures.
REST API Tool
Agent
↓
Generative Orchestration
↓
Tool selection
↓
API
HTTP Request Node
Topic
↓
Explicit HTTP request
↓
API
The difference is important.
41. Deterministic vs Generative API Invocation
With a Topic:
User
↓
Topic logic
↓
Explicit HTTP Request
The developer controls exactly when the call happens.
With REST API Tools:
User
↓
Generative Orchestration
↓
Agent decides which Tool fits
↓
API
This represents a shift from:
explicit procedural orchestration
to:
semantic generative orchestration
Both approaches are useful.
42. REST Tool vs Power Automate
We could also build:
Agent
↓
Power Automate
↓
HTTP
↓
futebol.org
This introduces another layer.
Why might we do that?
Because Power Automate can handle:
Transformations
Conditions
Caching
Multiple API calls
Logging
SharePoint storage
Notifications
Complex workflows
But if our requirement is simply:
“Retrieve match information”
then:
Agent
↓
REST API Tool
↓
futebol.org
may be architecturally cleaner.
43. When Power Automate Might Become Useful
Suppose we want:
Retrieve match
↓
Transform data
↓
Save result to SharePoint
↓
Send Teams notification
↓
Update tracking list
That is no longer merely an API lookup.
It is a workflow.
Power Automate becomes much more appropriate.
44. Rate Limiting
External APIs frequently impose request limits.
For example:
Requests per minute
Requests per hour
Requests per day
Concurrent requests
We do not currently have authoritative futebol.org rate-limit information from the publicly indexed documentation we located.
Therefore, this must become part of our documentation investigation.
An Agent can potentially generate many API calls.
This makes rate limiting architecturally important.
45. The Agent Must Not Guess API Data
Suppose:
GetMatch
↓
API returns 404
The Agent should not invent a match.
Instead:
“The requested match wasn’t found by the external football data service.”
Similarly:
401
↓
Authentication problem
429
↓
Rate limit
500
↓
Provider error
These conditions should remain distinguishable.
46. Error Architecture
A robust design should think in terms of:
Agent
↓
REST Tool
↓
API
↓
Success?
YES
↓
Process response
NO
↓
Identify error class
↓
Explain appropriately
This is particularly important because LLMs are designed to generate language even when upstream information is incomplete.
47. Documentation Becomes Part of Agent Quality
This laboratory teaches an important lesson.
API documentation isn’t only for programmers.
It ultimately influences:
OpenAPI
↓
Tool definitions
↓
Parameter descriptions
↓
Generative Orchestration
↓
Tool selection quality
Therefore:
Better API documentation can indirectly produce better Agent behavior.
48. Documentation Hierarchy
For this integration, our evidence hierarchy should be:
- futebol.org official API documentation
- futebol.org official OpenAPI/Swagger specification
- futebol.org official authentication documentation
- futebol.org official examples
- Observed API responses from controlled testing
- Our architectural interpretation
We should clearly distinguish those layers in our technical notes.
49. What We Must Never Invent
We should never guess:
Base URL
Endpoint
API key name
Authentication scheme
OAuth URL
Token URL
Scope
Rate limit
Parameter format
Response schema
If documentation doesn’t define it, we investigate.
This is especially important for authentication.
50. Our Target Architecture
If futebol.org provides an appropriate REST API, our target architecture could become:
User
↓
Football Data Companion
↓
Instructions
↓
Generative Orchestration
↓
Select Football Tool
↓
Input Parameters
↓
Authentication
↓
futebol.org REST API
↓
JSON
↓
Tool Output
↓
Agent
↓
Adaptive Card / Natural Language
This architecture isolates responsibilities cleanly.
51. Security Boundaries
The complete security chain is:
User
↓
Copilot Studio Agent
↓
Tool
↓
Connection
↓
Credential / Token
↓
futebol.org
Every arrow represents a trust boundary that should be understood.
Questions include:
Who owns the API credential?
Does every user use the same credential?
Does each user authenticate separately?
Can the credential be revoked?
Does it expire?
Which operations can it perform?
What data can it retrieve?
52. A Read-Only Football Agent Is a Good Laboratory
This particular scenario is technically valuable because football information is largely read-oriented.
We can learn:
REST
OpenAPI
Authentication
Tools
Generative Orchestration
JSON
Parameters
Responses
Errors
Adaptive Cards
without immediately giving the Agent dangerous enterprise write capabilities.
Later we can transfer the same architecture to SharePoint or internal APIs.
53. From Football to Enterprise Architecture
Today:
Football Agent
↓
Get Match
Tomorrow:
Corporate Agent
↓
Get Service Request
Today:
Get Team
Tomorrow:
Get Employee Asset
Today:
Get Competition
Tomorrow:
Get Project
The technical pattern remains:
User Intent
↓
Orchestration
↓
Tool
↓
Authentication
↓
REST API
↓
Structured Response
↓
Agent
The football scenario therefore becomes a safe laboratory for a highly reusable enterprise architecture.
54. Authentication Decision Tree
A useful decision tree for our futebol.org investigation is:
Does API require authentication?
↓
NO
↓
Copilot Studio Authentication = None
or:
YES
↓
Does documentation specify API Key?
↓
YES
↓
Identify exact parameter name
↓
Header or Query?
↓
Configure API Key
or:
Does documentation specify OAuth 2.0?
↓
YES
↓
Identify Client registration
↓
Authorization URL
↓
Token URL
↓
Refresh URL
↓
Scopes
↓
Configure OAuth 2.0
If none of these match:
↓
Stop
↓
Investigate supported authentication architecture
We should never force an unsupported authentication model.
55. Our Technical Investigation Checklist
Before connecting futebol.org to Copilot Studio, document:
| Question | Status |
|---|---|
| Official API documentation found? | To verify |
| API base URL identified? | To verify |
| OpenAPI available? | To verify |
| OpenAPI version? | To verify |
| Authentication required? | To verify |
| API key required? | To verify |
| OAuth supported? | To verify |
| Required headers identified? | To verify |
| Endpoints documented? | To verify |
| Response JSON documented? | To verify |
| Error codes documented? | To verify |
| Rate limits documented? | To verify |
| Terms of use verified? | To verify |
| Read/write capabilities identified? | To verify |
| API tested independently? | Not yet |
| OpenAPI validated? | Not yet |
| Imported into Copilot Studio? | Not yet |
This table prevents assumptions from quietly becoming architecture.
56. Copilot Studio Configuration Checklist
Once the API is understood:
| Step | Copilot Studio Configuration |
|---|---|
| 1 | Open Agent |
| 2 | Open Tools |
| 3 | Select Add a tool |
| 4 | Select New tool |
| 5 | Select REST API |
| 6 | Upload OpenAPI |
| 7 | Review API description |
| 8 | Select Solution |
| 9 | Configure Authentication |
| 10 | Select API operations |
| 11 | Review Tool names |
| 12 | Improve Tool descriptions |
| 13 | Review input parameters |
| 14 | Improve parameter descriptions |
| 15 | Review outputs |
| 16 | Publish Tool |
| 17 | Create Connection |
| 18 | Add Tool to Agent |
| 19 | Test Tool directly |
| 20 | Test Generative Orchestration |
| 21 | Inspect Agent response |
| 22 | Test failure scenarios |
| 23 | Test authentication expiration/failure |
| 24 | Test Adaptive Card rendering |
This follows the workflow currently documented by Microsoft for REST API Tools.
57. Final Technical Model
The entire integration can now be understood as:
Documentation
tells us what the external service supports.
↓
Authentication
determines how access is established.
↓
OpenAPI
describes the API contract.
↓
REST API Tool
exposes selected API operations.
↓
Descriptions
explain those operations semantically.
↓
Generative Orchestration
determines when a Tool is appropriate.
↓
Parameters
carry information from the Agent to the API.
↓
HTTP
transports the request.
↓
futebol.org
processes the request.
↓
JSON
returns structured information.
↓
Tool Output
makes the result available to the Agent.
↓
Agent
interprets the result.
↓
Adaptive Card / Natural Language
presents the result to the user.
Final Reference Table
| Layer | Responsibility | Football Example | Question We Must Answer |
|---|---|---|---|
| User | Express intent | “Show match 456” | What does the user want? |
| Agent | Coordinate interaction | Football Data Companion | What should happen? |
| Instructions | Define behavior | Prefer football Tools for live data | How should the Agent behave? |
| Generative Orchestration | Select capability | Choose GetMatch | Which Tool fits? |
| Tool Description | Explain capability semantically | Retrieve one football match | When should this Tool be selected? |
| REST API Tool | Expose external capability | GetMatch | What can the Agent call? |
| OpenAPI | Define machine-readable contract | Match operation | How does the API work? |
| Endpoint | Identify resource | To be verified | Where is the resource? |
| HTTP Method | Define operation | Likely GET for retrieval | What operation is performed? |
| Parameter | Supply request data | Match ID | What input is required? |
| Authentication | Establish identity/access | To be verified | How is access authenticated? |
| API Key | Shared credential model | If documented | What secret is required? |
| OAuth 2.0 | Identity-aware authorization | If documented | Who is granting access? |
| Scope | Restrict OAuth access | If documented | What permission is requested? |
| Connection | Runtime access context | Copilot Studio connection | Which credentials are used? |
| futebol.org | External data provider | Football data | What is the source of truth? |
| JSON | Structured API response | Match data | What did the API actually return? |
| Tool Output | Bring API result into Agent context | Match object | What can the Agent reason over? |
| Adaptive Card | Presentation layer | Match card | How should data be displayed? |
| HTTP Status | Describe operation result | 200/401/404/429/500 | Did the call succeed? |
| Rate Limit | Control API consumption | To be verified | How frequently can we call it? |
| Logging | Observe calls | Request/result | What happened? |
| Security | Protect API/data | Credential + authorization | Who can access what? |
| Knowledge | Provide static/contextual information | Football rules/documentation | What does the Agent know? |
| Action | Execute external capability | Retrieve football data | What can the Agent do? |
Authentication Summary
| Authentication | Copilot Studio Support | Credential | User Identity | Typical Scenario |
|---|---|---|---|---|
| None | Yes | None | No external identity | Public API |
| API Key | Yes | API key | Usually credential-oriented | Data/provider API |
| OAuth 2.0 | Yes | Access token | Can represent individual authorization | Enterprise/user-specific API |
| Custom/Other | Must be evaluated | Depends | Depends | May require another architecture |
The Central Lesson
The most important lesson from this architecture is:
Do not begin with Copilot Studio. Begin with the API contract.
The correct engineering sequence is:
Documentation → Authentication → API Test → OpenAPI → Tool → Orchestration → Agent → Presentation
If we cannot confidently explain the first three elements, we are not yet ready to configure the Tool.
For our futebol.org experiment, that is particularly useful because it prevents us from guessing the API’s authentication architecture.
Instead, we will treat the external API as a system that must first be understood.
Only then will we teach Copilot Studio how to use it.
Official Microsoft Documentation
Microsoft Learn — Extend your agent with tools from a REST API (Preview)
Microsoft Learn — Make HTTP requests in Copilot Studio
Microsoft Learn — Extend the capabilities of your agent
Microsoft Learn — Configure API key authentication
